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

Parameters 템플릿 컨텍스트

parameters: 축은 Release가 채우고 계약으로 검증된 파라미터 값을 담습니다. 이 값에 대한 접근성은 두 가지 병렬적인 멘탈 모델이 결정합니다.

  • 값 템플릿 표면(Aggregate 내부의 component / feature / sub-aggregate values: 문자열, 그리고 Recipe valuesMapping, FeatureRecipe injectMapping 및 provides, Workload 본문)은 파라미터 값을 이미 보간된 리터럴로 소비합니다. 해석 단계 내부의 보간 패스는 Aggregate의 전체 텍스트를 템플릿으로 평가하고 모든 {{ .parameters.<slot> }} 참조를 해석된 값으로 치환합니다. 다운스트림 값 템플릿 표면은 자신의 템플릿 컨텍스트에서 .parameters를 직접 보지 않습니다.
  • 경로 템플릿 표면(Release 경계에서 운영자가 작성하는 directory: 및 subDirectory: 템플릿)은 렌더링 중 경로 템플릿 평가 시점에 .parameters.<slot>을 직접 읽습니다. 병합된 파라미터 맵은 렌더링이 끝날 때까지 읽을 수 있는 상태로 유지되므로, 경로 템플릿은 닫힌 허용 목록에 맞춰 .parameters를 읽을 수 있습니다.

경로 템플릿은 .parameters를 직접 읽고 값 템플릿은 읽지 않는 이 비대칭적 권한 부여 덕분에 각 계층은 자신에게 필요한 것을 소유합니다. 개발자 측 values:는 이미 해석된 환경별 데이터를 값 템플릿으로 전달하고, 운영자 측 경로 템플릿은 Aggregate의 values 스키마를 거쳐 왕복하지 않고도 region / environment / account-id 파라미터를 참조합니다.

이 페이지에서는 보간 패스, 슬롯별 값 형태, Aggregate YAML 문자열 내부의 접근 패턴, 경로 템플릿 예외, 그리고 병합된 맵을 읽을 수 있는 기간을 설명합니다. 더 넓은 Recipe / FeatureRecipe 템플릿 컨텍스트 형태(.values, .infra, .uses 등)는 template-context-contract.md를 참조하십시오. 컴파일 파이프라인 전반에 걸친 템플릿 위치별 가용성은 expansion-matrix.md를 참조하십시오. Aggregate의 타입이 지정된 파라미터 계약 선언 형태는 entities/aggregate.md §“Typed parameter contracts”를 참조하십시오. 경계의 directory: / subDirectory: 평가 시 .parameters.<slot>을 포함하는 경로 템플릿 변수 허용 목록은 path-template-variables.md를 참조하십시오.

매개변수 수명 주기

컴파일러는 매개변수를 순서가 정해진 네 단계로 해석합니다.

  1. 계약 읽기 — Aggregate의 spec.parameters: 블록은 Release 값을 살펴보기 전에 그 자체로 검사되므로, 아무것도 제약할 수 없는 슬롯은 어떤 Release도 값을 제공하지 않더라도 빌드를 중단시킵니다. 매개변수 자체 선언에 음수 minLength 또는 maxLength가 있으면 Aggregate를 로드할 때 매개변수와 키를 명시하며 거부됩니다. 모든 pattern은 슬롯 자체에 있든 items, properties 또는 valuesType 아래의 중첩된 계약 안에 있든 정규 표현식으로 컴파일되며, 컴파일되지 않는 패턴은 매개변수, 패턴, 이유를 명시하며 거부됩니다. 중첩된 계약 안의 길이 제한은 이 하한을 적용받지 않습니다. entities/aggregate.md를 참조하십시오.
  2. 기본값 채우기 — default:가 정의되어 있고 Release가 제공한 값이 없는 슬롯은 기본값을 받습니다. 이 시점에 .parameters 맵을 사용할 수 있습니다.
  3. 매개변수 계약 검증 — 병합된 맵의 각 값은 Release가 제공했든 default:가 채웠든 Aggregate의 spec.parameters.<slot>에 선언된 type / enum / min / max / pattern / 중첩 구조 제약에 대해 검증됩니다. pattern은 계약을 읽을 때 컴파일된 표현식과 대조됩니다. .parameters 맵은 검사 대상인 구조화된 페이로드로서 검증기의 메모리 내 컨텍스트에 존재합니다.
  4. 보간 — 컴파일러는 Aggregate의 전체 텍스트를 YAML로 읽기 전에 템플릿으로 평가하고, 모든 {{ .parameters.<slot> }} 참조를 해석된 값으로 바꿉니다. 텍스트의 다른 {{도 템플릿 구문으로 읽히므로, 자체 이중 중괄호를 담은 값은 각 {{를 {{"{{"}}로 씁니다(자체 이중 중괄호를 담은 텍스트 참조). 보간은 값 템플릿 표면을 위한 치환 경로입니다. 이 단계 이후 값 템플릿 컨텍스트에는 더 이상 .parameters가 없으며, 주변 values: 문자열에 기록된 해석된 값을 사용합니다. 병합된 맵은 경로 템플릿 평가를 지원하기 위해 보간 이후에도 렌더링 전체에 걸쳐 읽을 수 있는 상태로 유지됩니다. 읽을 수 있는 수명은 빌드의 수명으로 제한됩니다. 컴파일러는 해석된 뷰를 호출자에게 반환하지 않고 이를 사용하는 컴파일에 넘기므로, 해당 빌드 밖에서는 맵에 접근할 수 없습니다. 경로 템플릿 표면(Release directory: / subDirectory:)은 렌더링 중에 path-template-variables.md에 문서화된 닫힌 허용 목록에 따라 .parameters.<slot>을 읽습니다.

Aggregate YAML 문자열 안의 템플릿(component values:, feature values:, sub-aggregate parameters: 전달 표현식)은 보간 단계에서 표준 Go 템플릿 구문으로 .parameters 맵을 읽습니다. Recipe 및 FeatureRecipe 파일 안의 템플릿은 템플릿 컨텍스트에서 .parameters를 받지 않습니다(표면별 계약은 아래 “다운스트림 템플릿 컨텍스트와의 경계”를 참조하십시오).

자체 이중 중괄호를 포함하는 텍스트

텍스트 전체가 템플릿이므로, 템플릿이 아니라 값에 속하는 이중 중괄호도 템플릿 액션으로 읽힙니다. 흔한 경우는 component의 values:에 담긴 플로 플랫폼의 정의입니다. n8n은 노드의 매개변수에 있는 각 표현식을 ={{ $json.body.message }}처럼 이중 중괄호로 감싸고, Flowise 프롬프트는 변수를 {{question}}으로 지정하며, Flowise 챗플로는 두 노드 사이의 각 연결에 대해 {{chatOpenAI_0.data.instance}}를 씁니다. 또한 Langflow 내보내기에는 구성 요소의 소스 코드가 담기는데, 여기에도 중괄호가 나타날 수 있습니다. 이를 그대로 Aggregate에 쓰면 빌드가 Aggregate에서 E0158로 중단되며, 이는 Fatal halts의 “A {{ .parameters.* }} reference cannot be interpolated(해당 매개변수 참조를 보간할 수 없음)” 항목에 설명되어 있습니다. 그 사유에는 템플릿 엔진이 읽지 못한 줄과 첫 번째 토큰이 표시됩니다. n8n 표현식의 경우 undefined variable "$json"입니다. YAML 주석도 템플릿 텍스트이므로, 주석에 쓴 {{도 같은 방식으로 빌드를 중단시킵니다.

이러한 값의 각 {{는 {{"{{"}}로 작성합니다. 이는 결과가 문자열 {{인 템플릿 액션이므로 보간 시 두 중괄호가 복원됩니다. 닫는 }}는 액션 밖에서는 일반 텍스트이므로 별도 처리가 필요 없습니다. 보간은 Aggregate의 텍스트에 대해 한 번만 실행되고, Recipe 템플릿은 .values에서 읽은 내용을 데이터로 출력하므로, 복원된 중괄호는 내보낸 그대로 렌더링 결과에 도달합니다.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

플랫폼은 "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}"를 받습니다.

이러한 정의는 위와 같이 블록 스칼라(|)에 두십시오. 블록 스칼라에서는 이스케이프의 따옴표가 일반 문자입니다. Aggregate의 텍스트는 보간되기 전에 YAML로도 읽히는데, 큰따옴표로 감싼 YAML 문자열 안에서는 이스케이프의 "가 문자열을 닫으므로 파일이 더 이상 파싱되지 않고 빌드는 YAML 오류로 중단됩니다.

.parameters.<slot> 접근 패턴

선언된 각 파라미터 슬롯은 .parameters 맵의 필드로 접근할 수 있습니다. 타입에 맞는 접근은 선언된 type과 일치합니다.

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

보간 단계는 .parameters 맵을 대상으로 Go 템플릿을 평가하며, 그 결과가 문서 안의 템플릿 표현식을 그 자리에서 대체합니다. 이후 Component / Feature의 values: 스키마가 해석 과정의 보간 후 스키마 검증 단계에서 결과 값을 검증합니다.

따옴표가 끌어올려지는 타입을 결정합니다

문자열 리프를 대상으로 하는 참조에는 따옴표를 붙이고, 그 밖의 모든 선언 타입에는 따옴표 없이 둡니다. 이 규칙은 Aggrega가 추가한 것이 아니라 YAML 자체의 규칙입니다. 보간은 충족된 값을 문서의 바이트에 대입할 뿐 다른 일은 하지 않으므로, 이어지는 파싱은 다른 스칼라를 읽을 때와 똑같이 그 결과를 읽습니다. 따옴표 없는 {{ .parameters.cache_ttl_seconds }}는 충족된 값 자체의 타입을 가지며, 이 덕분에 정수 파라미터가 정수 리프에, 불리언 파라미터가 불리언 리프에 도달할 수 있습니다. 따옴표를 붙인 "{{ .parameters.cache_ttl_seconds }}"는 문자열을 가지며, integer 또는 boolean으로 선언된 리프는 이를 거부합니다. 작성된 값은 해당 Component 또는 Feature의 values: 스키마에서 타입 검사에 실패하며, 진단은 문자열이 함께 위반했을 값 범위 제약이 아니라 타입 불일치를 지목합니다.

다른 텍스트와 스칼라를 공유하는 참조는 어떻게 작성하든 문자열이 됩니다. 대입된 문서에는 읽을 스칼라가 하나뿐이기 때문입니다. image: app:{{ .parameters.tag }}는 app:1.4.0을 만듭니다. 문자열이 아닌 파라미터를 문자열 리프에 넣어야 할 때 사용할 형식이 바로 이것입니다.

객체 타입 및 배열 타입 슬롯 접근

객체 타입 매개변수 슬롯은 선언된 속성을 .parameters.<slot> 맵의 중첩 필드로 노출합니다. 배열 타입 슬롯은 Go 템플릿 슬라이스 의미 체계(range, index, len)를 노출합니다.

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

배열 타입 매개변수 슬롯은 range를 통한 반복을 지원합니다:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Release가 제공하는 각 요소는 보간 전에 items 계약에 대해 검사되므로, 호스트 이름이 아닌 값(예: *)은 매개변수, 요소, 형식을 명시하며 빌드를 중단시킵니다. format이 허용하는 이름과 각 이름이 검사하는 내용은 vocabulary/compact-form-authoring.md에 나열되어 있습니다.

보간 중에는 Sprig 템플릿 라이브러리를 사용할 수 있으며, 배열을 문자열로 간결하게 변환하는 join 같은 헬퍼를 제공합니다:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

기본값 채우기 의미론

default: 선언이 있는 매개변수 슬롯은 Release가 해당 슬롯을 생략하면 기본값을 받습니다. 기본값은 계약 검증 단계가 실행되기 전에 적용되므로, 검증은 확정된(Release가 제공한 값 또는 기본값) 값을 대상으로 합니다.

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

required: true로 표시되고 default:가 없는 슬롯은 Release가 이를 생략하면 빌드 시점 오류(E0165)를 발생시킵니다. 이 오류는 작성자가 수정할 수 있도록 슬롯과 계약 내 그 위치를 명시합니다. required: true도 default:도 없는 슬롯은 선택 사항입니다. 생략되면 그에 대한 각 참조는 빈 값으로 보간되고, 그 결과는 Component의 values: 스키마가 판정합니다.

중첩 객체 매개변수

매개변수가 type: object를 선언하고 그 properties:의 자식들이 각자 default: 값을 가지는 경우, 세 가지 작성 방식이 서로 다른 결과를 냅니다. 매개변수 선언이 단일 스칼라가 아니라 구조화된 객체 — 데이터베이스 구성, 기능 플래그 묶음, 타임아웃·재시도 정책 — 일 때 이 차이를 이해하는 것이 중요합니다.

사례 1 — Release가 부모 슬롯을 생략합니다. 계약의 자식 기본값이 채워집니다. 중첩 기본값을 선언한 Aggregate 작성자는 의도한 동작을 얻습니다. 운영 측이 슬롯을 제공하지 않으면 구성은 문서화된 기본값을 사용합니다.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

사례 2 — Release가 부모를 명시적인 빈 맵으로 작성합니다. 명시적인 빈 값은 의도적인 옵트아웃으로 존중됩니다. 자식의 기본값은 채워지지 않으며, 슬롯은 비어 있는 상태로 남습니다. 운영 측이 재정의 값을 제공하지 않고 계약의 중첩 기본값을 억제하려는 경우 — 예를 들어 다운스트림 소비자가 슬롯이 존재하되 비어 있기를 기대하는 경우 — 이 형식을 사용합니다.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

사례 1과의 차이는 의도된 것입니다. 운영 측은 “기본값 사용”(슬롯 생략)과 “기본값 억제”(슬롯을 {}로 작성)를 모두 표현할 수 있습니다. 이는 Aggrega가 어노테이션에서 명시적 null을 다루는 방식과 같습니다. aggrega.ai/<key>: null로 작성된 어노테이션은 어노테이션을 아예 생략하는 것과는 구별되는 의도적인 옵트아웃입니다.

사례 3 — Release가 부모를 부분적으로 작성합니다. Release가 제공한 자식은 작성된 값을 가지며, Release가 제공하지 않은 자식은 기본값으로 채워집니다.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

이는 일부 필드만 재정의하고 나머지는 계약 기본값으로 두려는 Release 작성자에게 일반적인 경우입니다.

각 형식을 사용하는 경우

  • 계약의 기본값이 적용되기를 원할 때는 슬롯을 생략합니다.
  • 슬롯이 존재하되 비어 있기를 의도적으로 원할 때 — 계약의 기본값이 환경에 맞지 않고 재정의 값도 없을 때 — {}를 작성합니다.
  • 일부는 재정의하고 나머지는 계약의 기본값을 사용하려 할 때는 부분적으로 작성합니다.

“기본값을 달라”는 의도로 database: {}를 입력한 Release 작성자는 예상과 다른 결과를 보게 됩니다. 확정된 값은 채워진 기본값이 아니라 비어 있습니다. 기본값을 얻으려면 슬롯을 완전히 생략합니다.

세 가지 사례의 분기는 모든 중첩 깊이에서 형제 단위로 이루어집니다. { connection: {}, other_field: "x" }로 작성된 부모는 connection이 비어 있고(깊이 1의 사례 2) other_field가 Release가 제공한 값(깊이 0의 사례 3)인 확정 트리를 만듭니다. 사례는 하위 트리 전체에 대한 단일 결정이 아니라 각 형제마다 독립적으로 분기됩니다.

다운스트림 템플릿 컨텍스트와의 경계

비대칭적인 허용, 즉 경로 템플릿은 .parameters를 직접 읽고 값 템플릿은 읽지 않는다는 점이 이 경계에서 핵심이 되는 구분입니다. 표면별 경계 의미는 다음과 같습니다.

  • {{ .parameters.X }}를 작성하는 Aggregate component-values: 템플릿은 보간 시점에 올바르게 해석됩니다. 해석된 리터럴은 YAML 문자열의 해당 위치에 그대로 기록됩니다.
  • {{ .parameters.X }}를 작성하는 Recipe valuesMapping: 템플릿은 값 템플릿 표면이며, 템플릿 컨텍스트는 .parameters를 포함하지 않습니다. valuesMapping:에서 환경별 변형이 필요한 작성자는 해석된 .values.<key> 소비 경로를 통해 이를 표현합니다. 즉 Aggregate가 파라미터를 노출하고, Component의 values:에서 이를 참조하며, Release가 이를 채우고, 보간 이후의 값이 Recipe까지 전달됩니다.
  • FeatureRecipe injectMapping:, provides: 또는 pipeline.with: 템플릿은 값 템플릿 표면이며, Recipe valuesMapping:과 같습니다. .parameters는 템플릿 컨텍스트에 없습니다.
  • Workload 본문 템플릿(Recipe 내부의 workload: 내용)은 값 템플릿 표면이며, 마찬가지입니다.
  • 경로 템플릿(Release 경계의 directory: / subDirectory:)은 예외입니다. 경로 템플릿 컨텍스트는 닫힌 허용 목록에 대해 .parameters.<slot>을 포함하며, 참조는 렌더링이 각 경계의 출력을 배치할 때 해석됩니다. 전체 경로 템플릿 변수 매트릭스는 path-template-variables.md를 참조하십시오.

네 도메인의 소유권 경계는 특정 파이프라인 단계에서 파라미터 맵이 메모리에 존재하는지 여부가 아니라 어떤 표면이 파라미터를 받는지에 의해 유지됩니다. 경로 템플릿은 운영자가 작성하고 소유합니다. 여기에 직접 파라미터 접근을 허용하면 운영자의 관심사(환경별 아티팩트 레이아웃)가 운영자 표면 안에 머무릅니다. 값 템플릿은 카탈로그가 작성합니다. 여기에 직접 파라미터 접근을 허용하지 않으면 카탈로그 측 작성이 Aggregate-as-Single-Source-of-Truth 계약과 느슨하게 결합된 상태로 유지됩니다.

병합된 파라미터 맵은 모든 렌더 단계가 완료될 때까지만 읽을 수 있으며, 그 이후에는 읽을 수 없습니다. 이 맵은 해당 맵이 해석된 컴파일에서만 접근할 수 있으므로, 그 수명은 빌드의 수명으로 한정됩니다.

필러 간 연결

매개변수는 해석 과정에서 주변 values 문자열에 보간됩니다. 보간된 값은 Aggregate가 자신의 범위에서 작성하는 모든 필러에 들어갈 수 있습니다. 컴포넌트 values: 문자열, 기능 values: 문자열, 하위 aggregate의 parameters: 전달 선언(부모 Aggregate의 매개변수 값이 해석된 뒤 자식 Aggregate의 매개변수 슬롯으로 전파됨), 그리고 메타데이터 name: / labels: 문자열이 이에 해당합니다.

이 연결은 단방향입니다. 매개변수 값은 Release가 제공한(또는 기본값으로 채워진) .parameters.<slot>에서 참조 위치의 YAML 문자열로 흐릅니다. 매개변수는 반대 방향으로 흐르지 않습니다. 매개변수는 values: 필드, provides: 필드 또는 다른 어떤 필러의 내용도 읽을 수 없습니다. 이 방향성은 매개변수 계약이 컴파일 타임에만 적용된다는 보장의 일부입니다.

교차 참조

  • Aggregate의 타입이 지정된 매개변수 계약 선언 형태: entities/aggregate.md §“Typed parameter contracts”.
  • Recipes가 기본 렌더링 시점에 사용하는 더 넓은 템플릿 컨텍스트(.values, .infra, .uses, .context.* 등): template-context-contract.md.
  • 컴파일 파이프라인 전반에 걸친 템플릿 지점별 가용성(어떤 평가 지점에 어떤 필드가 존재하는지): expansion-matrix.md.
  • 매개변수 호이스팅 체크리스트(순차적인 네 가지 작성 접점 — Aggregate 선언, values 참조, Release 충족, Recipe 사용): vocabulary/data-pillars.md §“The parameter-hoisting checklist”.
  • 더 넓은 데이터 축 집합(values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.