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

Aggregate

Aggregate 엔터티의 개념적 역할(도메인 1 — 개발자의 선언적 토폴로지 청사진)은 architecture/04-entity-taxonomy.md에서 다룹니다. 구성 패턴(서브시스템, 중첩 aggregate, Zero-Port 관례, 파라미터 호이스팅)은 architecture/06-data-taxonomy-and-composition.md에서 다룹니다. 이 페이지는 Aggregate 카탈로그 작성 인터페이스, 그중에서도 카탈로그 배포를 위한 재사용 가능한 Aggregate 모듈 작성을 다룹니다.

Component 범위: 기본 서브시스템

Aggregate는 컴포넌트를 서브시스템으로 구성합니다. 서브시스템은 횡단 관심사(데이터 계층, 에지 계층)를 위한 이름 있는 그룹으로, 자체 어노테이션 캐스케이드를 가집니다. 대부분의 Aggregates에는 그룹이 하나뿐이므로 별도의 절차가 필요하지 않습니다.

단일 범위(기본값). 컴포넌트를 spec.components: 바로 아래에 작성하고 subsystems: 블록은 생략합니다:

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

컴파일러는 이 컴포넌트들을 합성된 default 서브시스템으로 접어 넣습니다. 노드 식별자는 바뀌지 않습니다. api는 default.api가 되지 않고 api로 유지됩니다. 따라서 이렇게 작성한 Aggregate는 명시적인 단일 서브시스템 형식과 서로 바꿔 쓸 수 있으며, 이를 가리킬 때(uses: 대상이나 진단에서)는 접두사 없는 spec.components.<name> 경로를 사용합니다. 합성된 범위는 내보낸 IR에 그대로 기록되지만(합성 서브시스템 표시를 가짐), 작성자가 쓰거나 읽는 경로에는 절대 나타나지 않습니다.

다중 범위. 컴포넌트가 서로 다른 횡단 그룹으로 나뉘는 경우 subsystems: 아래에 이름 있는 서브시스템을 선언합니다. 각 서브시스템은 자체 컴포넌트와 어노테이션 캐스케이드를 가지며, 하위 서브시스템을 더 중첩할 수 있습니다.

상호 배타성. spec.components:와 spec.subsystems:는 Aggregate 루트에서 상호 배타적입니다. 둘 중 하나만 작성해야 하며, 둘 다 작성할 수는 없습니다. 둘을 모두 선언한 문서는 로드 시점에 엔벨로프 오류로 중단됩니다. (개발자가 명시적으로 default라고 이름 붙인 서브시스템은 일반적으로 선언된 서브시스템이며, 정규화된 spec.subsystems.default.components.<name> 경로로 가리킵니다. 합성 범위의 경로 생략은 이름이 아니라 출처를 기준으로 합니다.)

재사용 가능한 Aggregate 모듈

Aggregates는 Release가 빌드하는 루트 Aggregate이자 재사용 가능한 모듈 역할을 모두 합니다. 부모 Aggregate는 자식 Aggregate를 component와 똑같이 선언하고 parameters를 하위로 전달할 수 있습니다. 강한 결합을 방지하기 위해 자식 Aggregates는 exportedComponents: 계약을 노출하여 안정적인 공개 인터페이스 이름을 확립합니다. 부모는 이 인터페이스를 통해서만 모듈의 component에 도달합니다. uses: 대상은 모듈 이름, 점, 그리고 모듈이 내보낸 별칭 중 하나로 이루어지며, 컴파일러는 그 별칭이 가리키는 내부 component로 엣지를 연결합니다. 그 밖의 이름 — 모듈 내부의 component 이름, 또는 그 안에 중첩된 모듈로 들어가는 경로 — 으로 모듈 안에 도달하려는 대상은 모듈과 그 모듈이 내보내는 별칭을 명시하며 빌드를 중단시킵니다. A uses target names a module’s component the module does not export (대상이 모듈이 내보내지 않은 모듈의 component를 지정함)를 참조하십시오.

명시적인 exportedComponents: 목록을 쓰는 이유. 모듈 작성자는 모듈의 component 중 어느 것이 공개 인터페이스를 이루고 어느 것이 구현 세부 사항으로 남을지 결정합니다. 부모는 목록이 공개하는 것만 지정할 수 있으므로, 공개된 각 이름이 여전히 어떤 component를 가리키는 한 모듈 내부를 리팩터링해도 — component 이름 변경, 하나의 component를 둘로 분할, worker를 관리형 서비스로 교체 — 어떤 부모도 깨지지 않습니다. 목록의 비용은 공개되는 component당 항목 하나이며, 가져오는 쪽이 사용해야 할 이름이 component 자신의 이름이라면 그 이름으로 공개할 수 있습니다(store: store). 같은 규칙이 구성 내부에도 적용됩니다. 모듈은 자신이 가져오는 모듈에 그 모듈이 내보낸 별칭을 통해 도달합니다. Release는 한 모듈의 두 component를 서로 연결할 수 있는데, 그 연결은 어떤 모듈의 인터페이스도 넘지 않기 때문입니다.

중첩 모듈의 인터페이스 다시 내보내기. exportedComponents: 항목은 직접 선언한 컴포넌트 대신 중첩된 하위 aggregate의 내보낸 별칭을 가리킬 수 있습니다. 즉 모듈이 가져온 모듈의 일부를 자신의 인터페이스 이름으로, 필요하면 새 이름으로 다시 공개하는 것입니다. 이렇게 다시 내보낸 별칭을 대상으로 하는 uses: 간선은 체인을 따라 전이적으로 구체적인 내부 노드까지 해석되므로, 모듈은 더 깊은 모듈의 내부 구조를 노출하지 않고 자신의 공개 인터페이스로 구성할 수 있으며, 소비자는 대상이 얼마나 깊이 중첩되어 있는지 알 필요가 없습니다. 안정적 인터페이스 규율은 모든 단계에서 유지됩니다. 각 모듈은 공개하기로 선택한 것만 다시 내보냅니다. 어떤 내부 노드로도 해석되지 않는 재내보내기 대상은 직접 지정한 대상이 매달린 경우와 같은 방식으로 명확하게 중단되며, 자기 자신으로 되돌아오는 재내보내기 체인은 끝없이 따라가지 않고 거부됩니다.

모듈의 선언은 Aggregate의 선언과 똑같이 검사됩니다. 모듈의 문서는 그 모듈을 가져오는 구성이 빌드될 때에만 읽히며, 그 선언은 그 시점부터 중첩 깊이와 관계없이 검사됩니다. 모듈 component 자체의 inject: 블록은 해당 타입의 spec.inject 허용 목록을 따라야 하며, 하나의 전달 키를 두 번 주장하는 것과 타입이 게시하지 않은 키를 읽는 것을 금지하는 규칙도 따라야 합니다. 모듈 자체의 subsystem 중 하나에 작성된 attachment는 그 Feature가 선언하는 소켓만 지정할 수 있으며, 모듈이 제공하는 component에 대해 Release가 작성하는 attachment도 마찬가지입니다.

모듈의 subsystem attachment는 그 component에 적용됩니다. 모듈이 자체 subsystem 중 하나에 연결한 Feature는 Aggregate의 subsystem attachment와 똑같이, 모듈이 그 subsystem 아래에 선언하는 모든 component(중첩된 subsystem 포함)로 캐스케이드되며, 오직 그 component에만 적용되고 가져오는 Aggregate에서 같은 이름의 subsystem 아래에 있는 component에는 절대 적용되지 않습니다. 이는 component 자체의 attachment 바로 다음에, 바깥 subsystem부터 안쪽 순서로 평가됩니다. 둘 다 작성한 필드에서는 같은 이름을 가진 component 자체의 attachment가 우선하며, 그것이 생략한 필드는 subsystem의 값을 유지합니다. 이것이 도달하는 각 component는 이를 Feature의 appliesTo에 비추어 검사합니다. 모듈 자체의 선언에 관한 발견 사항은 모듈과 그 문서 안의 키(예: .spec.subsystems.<subsystem>.features.<attachment>)를 명시하므로, 수정은 그 모듈을 가져오는 Aggregate가 아니라 선언이 있는 모듈에서 이루어집니다.

카탈로그 위치

재사용 가능한 Aggregate 모듈은 aggregate/ 종류 디렉터리 아래, 해당 metadata.name이 세그먼트 단위로 나타내는 경로에 위치하며, 말단에는 버전 디렉터리가 있습니다.

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

모듈 이름에는 공급자나 작성자를 나타내는 선행 {publisher} 세그먼트(표준 라이브러리는 core, 기업은 acme)가 올 수 있으며, 공개된 표준 라이브러리 모듈은 이 방식으로 이름이 붙어 있습니다. core/agenta는 aggregate/core/agenta/1.0.0/aggregate.yaml에 위치합니다. 단일 토큰인 이름은 한 단계 얕은 aggregate/{module-name}/{version}/aggregate.yaml에 위치합니다. 두 형식 모두 올바르며, 이름은 작성자가 쓰는 것이고 디렉터리는 그것을 그대로 반영합니다. 이 반영은 컴파일러가 검사하는 것이 아니라 카탈로그 관례입니다. 모듈은 파일이 놓인 위치가 아니라 선언한 이름으로 찾습니다.

OCI URI: hub.aggrega.ai/aggregate/{module-name}:{version}, 소문자로 변환됩니다. 따라서 core/agenta라는 이름의 모듈은 hub.aggrega.ai/aggregate/core/agenta:1.0.0에, db-module이라는 이름의 모듈은 hub.aggrega.ai/aggregate/db-module:1.0.0에 게시됩니다.

모듈 패턴

하위 모듈(aggregate/child-database-module/1.0.0/aggregate.yaml, hub.aggrega.ai/aggregate/child-database-module:1.0.0으로 게시):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"

부모 Aggregate:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

모듈 레이블

Aggregate가 재사용 가능한 모듈로 카탈로그에 게시될 때 YAML 엔벨로프에 metadata.labels를 가질 수 있습니다. 예를 들면 aggregate.aggrega.ai/tier: infrastructure나 aggregate.aggrega.ai/compliance: pci-dss입니다. 이 레이블은 모듈의 정체성을 기술하며 게시된 모듈 문서에 그대로 담기지만, 아직 이를 읽는 명령은 없습니다. 카탈로그 검색은 Aggregates를 색인하지 않고, 빌드 그래프는 모듈의 레이블도 카탈로그 이름도 담지 않으므로, 거버넌스 정책은 component를 그것이 나온 모듈로 선택할 수 없습니다.

중요한 구분. Aggregate 레이블은 카탈로그에서 재사용 가능한 모듈의 정체성을 설명합니다. 이 레이블은 하위 컴포넌트 노드로 전파되지 않습니다. 컴포넌트 레이블은 오직 도메인 2의 Component 카탈로그 엔터티에서만 옵니다. 개발자가 aggregate.aggrega.ai/tier: infrastructure 레이블이 붙은 모듈을 가져오더라도, 해당 모듈 내부의 개별 컴포넌트는 카탈로그에서 정의된 자신의 레이블(예: component.aggrega.ai/type: stateful-server)만 유지합니다. Aggregate 레이블은 IR 노드의 labels 사전에 절대 주입되지 않습니다.

복합 Aggregates / 모듈 패턴에 대한 전체 논의(Components에 하위 컴포넌트를 두지 않는 규칙 포함)와 subsystems 횡단 그룹화 메커니즘은 architecture/06-data-taxonomy-and-composition.md §6을 참조하십시오. 타입이 지정된 parameters 계약 작성 방식은 vocabulary/data-pillars를 참조하십시오.

타입이 지정된 매개변수 계약

Aggregate의 spec.parameters: 블록은 Release가 채우는 매개변수에 대한 타입이 지정된 계약을 선언합니다. 각 매개변수 슬롯은 선언된 type, 선택적 description, 선택적 default, 선택적 값 공간 제약 조건, 그리고 (객체 타입 슬롯의 경우) 중첩 구조를 가집니다. 컴파일러는 해석 중에, 매개변수 보간이 실행되기 전에 Release가 제공한 각 값을 계약에 대해 검증합니다.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

각 참조의 따옴표 사용은 의도적입니다. 따옴표가 끌어올려진 값이 어떤 타입으로 도착할지를 결정합니다. templates/parameters-context.md를 참조하십시오.

매개변수 슬롯 어휘

타입이 지정된 parameters: 블록은 간결한 형식의 어휘를 받습니다. type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate와 validateMessage(사용자 정의 검사와 그 검사가 보고하는 메시지), items(배열용), properties(객체용), valuesType(타입이 지정된 값 맵용), 그리고 required: true(슬롯별 표시)입니다. 이 키워드 중 세 가지, 즉 items, valuesType, 그리고 properties 아래의 각 항목은 단순한 설정이 아니라 계약을 값으로 받으며, 매개변수 슬롯에서 이 중첩 계약은 그것을 둘러싼 슬롯과 같은 타입 지정 형식으로 작성합니다. valuesType: boolean이 아니라 valuesType: { type: boolean }입니다. 보간 전에 컴파일러는 병합된 매개변수 맵을 이 선언들에 대해 직접 검사합니다. 어떤 슬롯도 선언하지 않은 매개변수는 거부되고, required: true로 표시되었지만 Release가 채우지도 않고 default가 제공하지도 않는 슬롯은 빌드를 중단시키며, 제공된 모든 값은 해당 슬롯에 선언된 type, enum 포함 여부, 문자열 슬롯의 경우 minLength와 maxLength 범위, pattern 정규 표현식, format, 그리고 min과 max 범위(숫자 슬롯의 값, 문자열 슬롯의 길이, 배열 슬롯의 항목 수)에 대해 검사됩니다. 객체 슬롯과 배열 슬롯은 재귀적으로 검사됩니다. properties 아래의 각 항목과 items에 대한 각 요소가 같은 방식으로 검사되고, valuesType 계약은 properties가 명명하지 않은 키를 관장하며, 어떤 선언도 명명하지 않은 중첩 키는 거부됩니다. schema: 필러가 이 키워드들을 다르게 표기하는 경우를 포함한 전체 키워드 어휘는 vocabulary/compact-form-authoring.md를 참조하십시오.

아래 키워드는 어떤 Release 값도 읽기 전에 선언 자체에서도 검사되므로, 아무것도 제약할 수 없는 슬롯은 어떤 Release도 그 슬롯을 제공하지 않더라도 빌드를 중단시킵니다.

  • 길이 범위는 0 이상입니다. 매개변수 자체의 선언에 있는 음수 minLength 또는 maxLength는 Aggregate가 로드될 때 Aggregate의 스키마에 의해 거부되며, 이때 매개변수와 키가 명시됩니다. 중첩 계약 안에서, 즉 items, properties 또는 valuesType 아래에서는 길이 범위가 작성된 그대로 읽히며 Aggregate가 로드될 때 그 하한이 적용되지 않으므로, 그곳에서도 0 이상으로 작성하십시오. 음수 minLength는 아무것도 제약하지 않고, 음수 maxLength는 모든 값을 거부합니다.
  • min과 max는 무언가를 제한해야 합니다. 불리언 슬롯이나 객체 슬롯에서는 이 쌍이 아무것도 제한하지 않으므로, 그곳에 작성된 min이나 max는 Aggregate를 불러올 때 매개변수와 키를 명시하며 거부됩니다.
  • 패턴은 컴파일되어야 합니다. 모든 pattern은 매개변수 계약을 읽을 때 정규 표현식으로 컴파일되며(슬롯 자체에서, 그리고 깊이와 관계없이 모든 중첩 계약 안에서), 컴파일되지 않는 패턴은 매개변수, 패턴, 이유를 명시하며 거부됩니다. 계약은 Aggregate에 도달하는 모든 빌드, pull, Release 검증에서 읽히며, 이는 Release 자체의 Aggregate이든 그 Aggregate가 가져오는 모듈이든 마찬가지입니다. 그런 다음 값 검사는 제공된 각 값을 컴파일된 바로 그 표현식과 대조합니다.
  • 형식은 컴파일러가 검사하는 것이어야 합니다. format은 email, uri, hostname, ipv4, ipv6, uuid, date-time, date 중 하나를 JSON Schema가 표기하는 방식 그대로 명명합니다. 그 밖의 이름, 예를 들어 emial 같은 오타나 password처럼 JSON Schema가 정의하지 않는 이름은 Aggregate가 로드될 때 매개변수를 명시하고 지원되는 이름을 나열하며 거부됩니다. 슬롯 자체에서는 Aggregate의 스키마에 의해, 깊이와 관계없이 중첩 계약 안에서는 매개변수 계약을 읽을 때 거부됩니다. 그런 다음 명명된 형식을 갖추지 않은 제공된 문자열은 매개변수, 값, 형식을 명시하며 거부됩니다. 각 이름이 무엇을 검사하는지는 vocabulary/compact-form-authoring.md에 있습니다.

객체 타입 및 배열 타입 매개변수

매개변수 슬롯은 중첩 객체와 타입이 지정된 요소의 배열을 포함하여 간결한 형식이 지원하는 모든 타입을 받습니다.

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

Release는 객체 타입 매개변수를 구조화된 YAML로 채우며, 컴파일러는 보간 전에 선언된 스키마에 대해 구조를 검증합니다. 객체의 필드를 참조하는 템플릿은 표준 Go 템플릿 구문을 사용합니다: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} 등.

매개변수 계약 검증

계약 자체는 읽힐 때 가장 먼저 검사됩니다. 위 “Parameter slot vocabulary”에서 설명한 길이 범위 검사와 패턴 검사가 이에 해당합니다. 이후 컴파일러는 매개변수 처리 중에 세 가지 하위 단계를 실행합니다.

  1. 기본값 채우기 — default:가 정의되어 있고 Release가 제공한 값이 없는 슬롯은 기본값을 받습니다. 중첩 객체 매개변수에는 부모 슬롯을 생략한 경우, 명시적으로 비워 둔 경우, 일부만 작성한 경우의 세 가지 작성 의미가 있습니다. 부모를 생략하면 자식의 기본값이 채워지고, 부모를 {}로 작성하면 명시적인 빈 값이 유지되며(자식의 기본값이 적용되지 않음), 부모를 비어 있지 않은 맵으로 작성하면 Release가 제공하지 않은 자식만 채워집니다. YAML 예제와 “각 형식을 언제 사용할지” 결정 가이드는 templates/parameters-context.md를 참조하십시오.
  2. 계약 검증 — 병합된 맵의 각 값은 Release가 제공했든 default:가 채웠든 선언된 type / enum / min / max / pattern / 중첩 구조 제약 조건에 대해 검증됩니다. 검증에 실패하면 문제가 된 슬롯, 제공된 값, 위반된 제약 조건을 명시하는 명확한 오류와 함께 빌드가 중단됩니다. default:가 없는 필수 매개변수가 누락된 경우에도 슬롯 이름과 함께 비슷하게 중단됩니다.
  3. 보간 — 컴파일러는 Aggregate를 YAML로 읽기 전에 그 전체 텍스트를 템플릿으로 평가하고, 모든 {{ .parameters.<slot> }} 참조(일반적으로 component / feature / 하위 aggregate의 values: 문자열 안에 있음)를 확정된 값으로 바꿉니다. 텍스트의 다른 모든 {{도 템플릿 구문으로 읽히므로, 자체적으로 이중 중괄호를 포함하는 값(예: 플로 플랫폼에서 내보낸 정의)은 자체 이중 중괄호를 포함하는 텍스트에서 설명하는 대로 각 {{를 {{"{{"}}로 작성합니다. 이 단계 이후 값 템플릿 표면은 이미 보간된 리터럴을 사용하며, 템플릿 컨텍스트에서 .parameters를 받지 않습니다.

병합된 매개변수 맵은 경로 템플릿 평가를 지원하기 위해 렌더링이 끝날 때까지 유지됩니다. Release 경계에서 운영자가 작성한 directory: 및 subDirectory: 템플릿은 렌더 시점에 닫힌 허용 목록에 따라 .parameters.<slot>을 직접 읽습니다. 경로 출력에는 환경별 아티팩트 배치를 위한 리전 / 환경 어휘가 필요하며, 이 비대칭적 허용은 Aggregate의 values를 거치지 않고 해당 운영자 관심사를 운영자 표면 안에 유지합니다. 맵은 모든 렌더링 단계가 완료될 때까지 읽을 수 있으며, 해당 맵이 확정된 컴파일에서만 접근할 수 있습니다. 개발자가 작성한 values:를 사용하는 recipe는 보간 후의 문자열을 보고, 경로 템플릿은 렌더링 동안 실시간 .parameters 데이터를 봅니다. 경로 템플릿 사용 가능 여부 매트릭스는 templates/expansion-matrix.md의 3행을, 경로 템플릿 변수 허용 목록은 path-template-variables.md를 참조하십시오.

더 폭넓은 매개변수 호이스팅 체크리스트(Aggregate 선언 → values 참조 → Release 충족 → Recipe 사용)와 필러 간 동작 방식은 vocabulary/data-pillars.md §“Parameters” 및 §“The parameter-hoisting checklist”를 참조하십시오. 보간 중에 노출되는 템플릿 컨텍스트 필드와 경로 템플릿 예외는 templates/parameters-context.md를 참조하십시오.

uses 엣지는 Aggregate가 선언하는 호출입니다

uses 엣지는 한 component가 다른 component를 호출한다는 Aggregate의 선언입니다. 컴파일러는 대상이 게시하는 값을 호출자에게 전달할 뿐 아무것도 제한하지 않습니다. 엣지 자체만으로는 호출자를 허용하지도, 다른 누구를 거부하지도 않으며, 엣지 없이 대상의 주소에 도달하는 workload도 똑같이 대상에 도달합니다.

누가 component를 호출할 수 있는지, 그리고 component가 무엇을 호출할 수 있는지를 제한하는 것은 운영자의 결정이며, Release에서 환경별로 내립니다. Release가 표준 라이브러리 카탈로그의 core/caller-allowlist Feature를 component에 연결하면, 빌드는 해당 component를 가리키는 uses 엣지를 가진 component, 그 component 자체의 pod, 그리고 연결이 명시하는 소스만을 정확히 허용하는 네트워크 정책을 작성합니다. 이에 대응하는 아웃바운드 측인 core/egress-allowlist는 연결된 component가 자신의 uses 엣지가 가리키는 component, 자신의 pod, 클러스터의 DNS, 그리고 Release가 나열하는 주소 범위에만 도달하도록 합니다. 그러면 Aggregate가 엣지로 선언하지 않은 호출은 클러스터의 네트워크 플러그인이 네트워크 정책을 적용하는 곳이라면 어느 쪽 끝에서든 거부될 수 있습니다. 따라서 값을 주입하지 않는 호출을 포함하여 component가 하는 모든 호출에 대해 엣지를 작성하십시오. 누락된 엣지는 울타리가 쳐진 component가 거부할 수 있는 호출입니다. model-server-caller-allowlist는 앞단의 게이트웨이를 통해서만 도달할 수 있는 모델 서버를 보여 줍니다.

연결 자체의 첨부: uses 항목의 features

컴포넌트가 상세한 uses: 형식으로 그리는 연결은 그 자체로 하나의 항목이며, target, inject, values 외에 features: 아래에 첨부를 가질 수 있습니다. 각 첨부는 소켓이 선언하는 슬롯을 키로 합니다. 소비하는 Component는 소켓의 featuresSchema에 그 소켓을 통해 연결되는 모든 연결이 채울 수 있는 슬롯을 나열합니다(Topology Sockets 참조). 이를 통해 한 컴포넌트가 자신이 접근하는 컴포넌트마다 서로 다른 자격 증명을 가질 수 있습니다. 예를 들어 두 모델을 두 개의 키로 호출하는 게이트웨이나, 모델에 자신만의 키를 제시하는 에이전트가 그렇습니다.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

연결의 첨부는 type(필수), 선택 사항인 description, 그리고 Feature를 위한 values를 가집니다. uses와 inject는 가지지 않습니다. 연결의 첨부는 중첩되지 않으며, 그 내용이 소비자에게 어떻게 전달되는지는 inject 블록이 아니라 소비하는 컴포넌트의 Recipe가 결정합니다. 둘 중 하나라도 작성한 문서는 로드될 때 해당 키를 명시하며 거부됩니다.

소켓이 선언하는 슬롯만 허용됩니다. 소켓의 featuresSchema에 나열되지 않은 이름의 첨부는 로드될 때 빌드를 중단시키며, 연결, 소켓, 컴포넌트, 그리고 소켓이 실제로 선언하는 슬롯을 명시합니다. 그 이름이 선언된 슬롯 중 하나와 한 번의 편집 차이라면, 의도했을 가능성이 높은 철자로 그 슬롯도 함께 알려 줍니다. 채워진 슬롯은 각 연결에서 해당 슬롯 자체의 선언을 따라야 합니다. Feature의 레이블이 충족하지 않는 selector는 이 항목에서 중단되고, 어느 연결에서든 비어 있는 required 슬롯은 그 연결을 명시하며 중단됩니다. 슬롯을 선언하지 않는 소켓은 그 연결에 어떤 첨부도 허용하지 않으며, 임시 소켓, 즉 Component가 선언하지 않았는데 Aggregate가 연결하는 소켓도 슬롯을 전혀 선언하지 않으므로 마찬가지입니다. 하위 모듈이 제공하는 컴포넌트도 같은 규칙을 따르며, 해당 오류는 하위 모듈 자체의 문서를 가리킵니다. A connection carries an attachment under a name its socket declares no slot for (연결이 소켓이 슬롯을 선언하지 않은 이름으로 첨부를 가짐)를 참조하십시오.

Feature가 그리는 연결은 첨부를 가지지 않습니다. 첨부된 Feature 자체의 uses: 블록은 컴포넌트에 있든 서브시스템에 있든 같은 형태로 작성되지만, 문서가 로드될 때 features:를 거부합니다. 그러한 연결에 필요한 자격 증명은 Feature가 자체 featuresSchema에 선언하는 슬롯을 채우며, Feature 옆에 첨부됩니다. A Feature’s Own Credential을 참조하십시오.

첨부가 갖는 이름. 각 연결 첨부는 소비하는 컴포넌트의 첨부가 되며, <alias>.<slot>이라는 이름을 가집니다. 즉 연결이 작성된 별칭, 점, 그리고 슬롯이며, 위의 예에서는 gpt.credential입니다. 점은 컴파일러가 조합하는 이름에 예약된 구분자로, Aggregate의 어떤 별칭, 슬롯, 첨부 이름에도 포함될 수 없습니다. 따라서 조합된 이름은 컴포넌트 자체의 features: 블록에 작성된 이름과 절대 같아지지 않으며, Release가 컴포넌트나 경계에 그 이름을 작성하면 거부됩니다(Per-edge connection configuration 참조). 이 이름은 Manifest의 인스턴스별 계층이 첨부의 키로 사용하는 이름이며(Flat URI mapping 참조), 진단과 IR 그래프가 첨부를 보고하는 이름이고, 첨부의 FeatureRecipe가 .attachment_name으로 읽는 값입니다(Names derived from a connection’s attachment 참조).

그 이후에는 다른 첨부와 똑같이 해석됩니다. Manifest가 그 Feature 타입을 FeatureRecipe에 바인딩하고, 그 values는 Feature의 스키마에 대해 검증되며(실패는 값을 작성한 연결 항목에서 보고됩니다), 그 FeatureRecipe는 첨부 자체의 values와 infra를 기반으로 렌더링됩니다. 컴포넌트 자체의 첨부와 다른 점은 두 가지입니다.

  • 소비하는 Recipe의 .features에 포함되지 않습니다. 이 기둥은 컴포넌트 자체 블록에 작성된 첨부만 담으므로, 자신의 첨부를 타입별로 찾기 위해 .features를 살펴보는 Recipe에게 연결의 자격 증명이 전달되는 일은 없습니다. Recipe는 연결의 첨부를 연결 자체에서 .context.uses.<alias>.features.<slot> 위치로, .features가 담는 것과 같은 형태로 읽으며, 해석된 provides도 포함됩니다(A connection’s attachments 참조).
  • 소비자에게만 적용됩니다. 대상의 렌더링 결과는 그 대상에 도달하는 연결이 무엇을 가지든 동일합니다.

작성된 블록의 그래프 사본. IR 그래프는 각 컴포넌트의 uses: 블록을 작성된 그대로 유지하며, 그 안에서 연결 첨부는 type과 description만 유지하고 values는 전혀 유지하지 않습니다. 값은 소비자가 가지는 첨부에 한 번만 나타나며, 그곳에서 Feature가 민감하다고 선언한 값은 숨겨집니다.

Release는 여기서 선언된 첨부의 크기를 infra로 지정하거나, 자신이 접근하는 연결에 자체 첨부를 추가할 수 있습니다. Per-edge connection configuration을 참조하십시오.

component 또는 module 끄기: active:

component 인스턴스와 sub-aggregate 모듈은 각각 해당 엔터티가 컴파일된 토폴로지에 포함될지 여부를 결정하는 active: 토글을 받습니다. 생략하면 엔터티가 존재하며, 이것이 기본값이자 일반적인 경우입니다.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

불리언을 직접 쓰거나, 불리언으로 해석되는 .parameters 기반 템플릿을 씁니다. 토글이 존재하는 이유는 템플릿 형식에 있습니다. Release가 parameter를 채워 엔터티의 존재 여부를 결정할 수 있으므로, 하나의 Aggregate가 배포하는 구성 요소가 서로 다른 환경들을 포괄할 수 있습니다. 이때 Release는 Aggregate가 선언하지 않은 것을 아무것도 선언하지 않습니다.

false 토글이 제거하는 것. 엔터티는 그래프가 만들어지기 전에 잘려 나가며, 이 제거는 연쇄적으로 적용됩니다. component는 자신의 uses: 엣지와 연결된 Features를 함께 가져가고, module은 자신이 기여한 모든 것, 즉 그 component들, 그 엣지들, 그 attachment들을 함께 가져갑니다. 제거된 엔터티가 가져온 것은 어느 것도 렌더링되지 않습니다. 제거가 미치지 않는 것은 살아남은 다른 곳에서 그 엔터티를 가리키는 참조이며, 이는 다음 단락에서 다룹니다.

살아남은 component가 제거된 component를 여전히 가리키면 빌드가 중단됩니다. api가 redis로 향하는 uses: 엣지를 선언하고 redis가 꺼져 있으면, 빌드는 엣지가 사라지도록 두지 않고 중단됩니다. 엣지가 사라지면 배포 시점에 api의 주입된 값이 조용히 비어 버리기 때문입니다. 둘 중 어느 쪽이 이 환경에 속하는지 결정하십시오. 대상을 다시 켜거나, 소비자를 같은 parameter로 제어하여 둘이 함께 빠지게 하거나, 소비자의 uses: 블록에서 엣지를 삭제합니다.

작성된 토글은 boolean으로 해석되어야 하며, 빈 값은 boolean이 아닙니다. 토글은 템플릿이 해석된 뒤 엄격하게 읽히며, boolean으로 파싱되지 않는 리터럴은 어떤 값으로도 기본 처리되지 않고 빌드를 중단합니다. 주의해야 할 경우는 값이 없는 파라미터를 읽는 토글입니다. 이 토글은 아무것도 아닌 값으로 해석되는데, 이를 “존재함”으로 읽으면 바로 그 파라미터로 제어하려던 엔터티가 배포되어 버립니다. 따라서 뒤에 아무것도 없이 active:를 작성하는 것은 키를 생략하는 것과 같지 않습니다. 아무도 작성하지 않은 토글만 기본적으로 존재함으로 처리됩니다. 모든 환경에 답이 있도록 spec.parameters에서 파라미터에 default:를 지정하거나, Release에서 그 파라미터를 채우십시오. 엔터티를 무조건 존재하게 하려면 active: 키를 비우지 말고 제거하십시오. 이 중단은 중단 조건 레퍼런스의 “An active: toggle does not resolve to true or false (active: 토글이 true 또는 false로 해석되지 않음)” 항목에 설명되어 있습니다.

꺼진 component도 Release에서 이름으로 지정할 수 있습니다. Release는 여전히 boundary에서 그 이름을 지정할 수 있으며, 이는 의도된 것입니다. component를 끄는 것은 작성 행위이며, 그 component를 구성하는 Release를 같은 편집에서 다시 작성할 것으로 기대하지 않습니다.

서브시스템과 컴포넌트의 어노테이션

서브시스템과 컴포넌트 인스턴스는 모두 annotations: 필드를 가집니다. Aggregate 표면에서 개발자가 작성한 어노테이션은 Aggregate 측 어노테이션 캐스케이드를 구동합니다. 서브시스템 어노테이션은 모든 중첩 서브시스템과 포함된 모든 컴포넌트로 전파되며, 더 가까운 수준의 재정의가 키 단위로 적용됩니다. Manifest의 mappings.features.annotations 맵은 빌드 시점에 어노테이션 키를 합성 Feature 연결로 변환하는 바인딩을 선언합니다. Aggregate-as-Authoring-Surface 불변 조건은 이러한 어노테이션이 바인딩의 maps.values 경로를 통해서만 라우팅되도록 제한합니다. maps.infra 경로만 선언하는 바인딩은 Aggregate 측이 아니라 Release 측에서 실행됩니다.

값의 형태

각 어노테이션 키는 네 가지 형태 중 하나를 가지며, “아무것도 선언하지 않음”, “값을 선언함”(스칼라 또는 구조화된 객체), “옵트아웃함”을 구분합니다.

  • 키 없음 — 해당 스코프는 이 어노테이션에 대해 값을 선언하지 않습니다. 중첩 서브시스템과 포함된 컴포넌트는 상위 스코프의 바인딩을 상속합니다.
  • 스칼라 문자열 — 단일 값입니다. Manifest 바인딩은 전체적으로 정확히 하나의 경로를 선언해야 하며, 스칼라는 그 경로로 라우팅됩니다.
  • 구조화된 객체 — 하위 키와 하위 값의 맵입니다. 객체의 각 하위 키는 Manifest 바인딩의 maps를 통해, 선언된 필러에 있는 대응 Feature 스키마 필드로 라우팅됩니다.
  • 명시적 YAML null — 해당 스코프는 이 키에 대해 상속된 바인딩을 자신의 하위 트리에서 제거합니다. 형제 컴포넌트와 형제 서브시스템은 상속을 유지하며, 옵트아웃한 스코프만 바인딩을 잃습니다.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

여러 필드를 가진 Features를 위한 구조화된 값

구성 가능한 필드가 여러 개인 Feature에는 구조화된 어노테이션 값이 적합합니다. 하나의 어노테이션 키가 한 번의 선언으로 여러 Feature 스키마 필드의 값을 전달합니다. Aggregate 측은 바인딩 맵 필러가 values인 하위 키만 실행하며, infra로 라우팅되는 하위 키는 Release 측 어노테이션에 둡니다.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

구조화된 값은 하위 키 단위의 깊은 병합으로 캐스케이드됩니다. 더 가까운 수준의 하위 키가 상위 하위 키를 재정의하며, 하위 키에 명시적 null을 두면 해당 스코프에서 상속된 하위 키가 억제되고 형제 하위 키는 유지됩니다. Release 측 infra 하위 키와의 교차 구성, 하위 키 단위 타입 검증, 선언된 type이 없는 스키마 필드에 대한 완화된 기본값 원칙 등 구조화된 값에 대한 전체 설명은 providers/well-known-annotations.md §“Structured annotation values”를 참조하십시오.

키별 독립성

각 어노테이션 키는 독립적으로 상속, 재정의, 옵트아웃됩니다. annotations.feature.myco/db-pool: null을 선언한 컴포넌트는 그 키에 대해서만 옵트아웃하며, 상위 서브시스템에서 상속된 다른 키는 계속 그 컴포넌트로 전파됩니다. 같은 서브시스템의 형제 컴포넌트는 각자의 어노테이션 맵을 독립적으로 유지하므로, 한 컴포넌트의 옵트아웃은 형제에 영향을 주지 않습니다.

최상위 컴포넌트 어노테이션

최상위 컴포넌트(서브시스템 안이 아니라 spec.components 바로 아래에 선언된 컴포넌트)에는 상속되는 캐스케이드가 없습니다. 이들의 annotations: 필드는 컴포넌트 스코프에 직접 값을 선언하며, 확장 과정에서 Manifest에 일치하는 바인딩이 있는 각 선언된 어노테이션으로부터 Feature 연결이 합성됩니다.

바인딩에 적용되는 Aggregate 측 캐스케이드 규칙, 측과 필러의 구분, 그리고 바인딩이 어노테이션을 합성 Feature 연결로 변환하는 과정을 보여 주는 종단 간 예제는 providers/well-known-annotations.md §“Aggregate-side annotation cascade”를 참조하십시오.

YAML 앵커 패턴(defs: 블록)

Aggregate 스키마는 선택적인 루트 수준 defs: 블록을 허용합니다. 이 블록은 표준 YAML 앵커(&anchor)와 참조(*anchor)를 담는 용도로만 쓰이는 YAML 문자열 목록입니다. 컴파일러는 이 블록의 내용을 전혀 읽지 않습니다. 이 블록은 작성자가 앵커 정의를 한곳에 선언하고 Aggregate의 나머지 부분 전체에서 참조할 수 있도록 존재하며, 이를 통해 컴파일러가 순회하는 평탄한 O(1) 딕셔너리를 잃지 않으면서 반복되는 값을 DRY하게 유지합니다. 이 메커니즘은 Manifest 엔터티의 동등한 defs: 블록과 같은 방식입니다.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

앵커는 YAML 파싱 시점에 해석되므로, 컴파일러가 values 블록을 읽을 때 *default_log_level은 이미 문자열 "info"입니다. defs: 블록은 앵커 정의를 두는 관례적인 위치입니다. YAML은 앵커를 어디에서나 선언할 수 있게 허용하지만, 앵커를 한곳에 모아 두면 Aggregate의 나머지 부분을 읽기 쉽게 유지할 수 있습니다. 이 블록은 선택 사항이며, 앵커가 필요하지 않은 Aggregates는 이 블록을 완전히 생략합니다.