extends와 implements
extends를 통한 상속
카탈로그 엔터티(Component, Feature)는 extends 키워드를 통한 단일 상속을 지원하며, 이를 통해 플랫폼 아키텍트는 공유 베이스 위에 특화된 엔터티를 구축할 수 있습니다. YAML 엔벌로프 딥 머지는 두 종류에 공통입니다. 확장하는 엔터티의 메타데이터, 레이블, 선언적 구조 테이블이 베이스의 일치하는 키를 덮어쓰며, 중첩된 맵은 재귀적으로 병합됩니다. 두 종류는 데이터 필러에서 갈라집니다.
이 페이지는 카탈로그 종류를 다루며, extends를 선언하는 종류가 이들만 있는 것은 아닙니다. Release와 Manifest도 이를 선언하는데, 둘 다 카탈로그에 색인되는 엔터티가 아니라 서로 나란히 작성되는 배포 측 문서입니다. 따라서 이들의 참조는 카탈로그 엔터티가 아니라 파일을 가리키며, 병합되는 것은 스키마가 아니라 작성 표면입니다. 이에 대해서는 entities/release.md와 entities/manifest.md를 참조하십시오.
Component의 extends는 구조를 합성하고 필러를 통째로 상속합니다
Component의 경우 extends는 metadata.labels, metadata.annotations, spec.featuresSchema(연결 슬롯), spec.usesSchema(토폴로지 소켓), spec.inject(자기 주입 허용 목록으로, 항목이 중복 없이 베이스 우선으로 이어 붙여집니다)를 합성합니다. 세 가지 데이터 필러인 values, infra, provides는 합성되지 않습니다. 확장하는 Component는 필러 내용을 작성하지 않습니다. 리터럴 마커 schema: inherited를 작성하고, 체인의 모든 깊이에서 베이스가 작성한 그대로의 schema: 블록을 받습니다.
게시된 Component 스키마는 이 마커를 필수이자 배타적인 것으로 만들며, 문서를 로드할 때 이를 벗어나는 각 경우를 각각 고유한 진단으로 거부합니다. extends:를 선언한 Component에서 schema: 아래에 필러 내용을 작성한 경우, 그곳에서 schema:를 완전히 생략한 경우, 그리고 extends:를 선언하지 않은 Component에 schema: inherited를 작성한 경우입니다.
여기서 두 가지 결과가 따르며, 이들은 서로 반대 방향으로 작용합니다.
- 키 집합은 베이스가 고정합니다. 확장하는 Component는 필러 키를 선언하지 않으므로, 베이스가 선언한 키를 숨기거나 삭제하거나 타입을 바꿀 수 없으며, 자체 키를 추가하지도 않습니다. 베이스의 인스턴스와 이를 확장하는 모든 것의 인스턴스는 동일한 필러 계약에 대해 검증됩니다.
- 제약 강화는
assertions:로 옮겨갑니다. 상속된 필러보다 적은 것을 허용해야 하는 특화는 좁힌 스키마 리프가 아니라 자기 자신에 대한 술어로 이를 표현합니다. 베이스core/base-server가tls_enabled: { type: boolean, default: true }를 선언한다면, TLS를 무조건 요구하는 특화는 다음과 같이 작성합니다.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}이 규칙은 상속된 필러 블록이 허용하는 값을 거부하며, 이것이 바로 여기서 말하는 제약 강화입니다. 반대 방향은 아예 표현할 방법이 없습니다. 특화는 제약을 담고 있는 리프를 다시 기술할 수 없으므로 상속된 제약을 완화할 수 없습니다. 전체 합성 표와 베이스-확장 쌍의 예제는 entities/component.md의 “Catalog Authoring: Extending Base Components”를 참조하십시오.
Feature의 extends는 필러를 합성합니다
Feature의 경우 자식의 schema:는 JSON Schema 2020-12 합성 의미론에 따라 베이스의 것과 합성되어, 작성된 인스턴스가 검증되는 단일 병합 스키마를 만듭니다. 자격 증명 Features, 즉 feature.aggrega.ai/kind: secret 레이블이 붙은 것들은 이를 사용해 공유 베이스 위에 구축합니다. 자식 자격 증명 Feature는 부모를 확장하여 그 볼트 쿼리 스키마를 상속하면서 제약을 좁힙니다.
컴파일러는 그 변경의 방향에 대해 입장을 취하지 않습니다. 합성은 구조적이므로, 베이스의 제약을 넓히는 자식 제약은 빌드를 중단하지 않고 합성되며 권고로 표시됩니다. 이를 거부하는 것은 없습니다. Feature 베이스의 제약은 카탈로그 작성자들이 리뷰를 통해 지키는 공유된 기대이지, 플랫폼이 감시하는 계약이 아닙니다.
implements를 통한 인터페이스 바인딩
Recipes와 FeatureRecipes는 spec 최상위의 implements: 키워드를 통해 Component 또는 Feature 인터페이스에 바인딩됩니다. 이 바인딩은 이 Recipe / FeatureRecipe가 어떤 카탈로그 인터페이스의 구체적인 구현인지 선언하며, 세 가지 형태의 버전 매칭을 지원합니다.
- 정확한 버전 —
implements: core/api-server:1.0.0— Component 타입의 특정 버전 하나와 매칭됩니다. - 메이저 호환 범위 —
implements: core/api-server:^1.0.0—>=1.0.0, <2.0.0(SemVer 메이저 호환)을 만족하는 모든 버전과 매칭됩니다. Recipe가 고정된 단일 버전이 아니라 호환 범위를 지원할 때 사용합니다. - 버전 없음 —
implements: core/api-server— Component 타입의 모든 버전과 매칭됩니다. Recipe가 해당 타입의 모든 버전을 지원할 때 사용합니다.
implements:는 Recipe를 선택하지 않습니다. 선택은 Manifest의 매핑이 합니다. 이 선언이 구동하는 것은 각 매핑 항목에 대한 일관성 검사(매핑된 타입의 버전이 매핑된 Recipe의 implements:를 세 가지 형식 중 하나로 만족하거나, 해당 Recipe가 그 타입이 확장하는 기반을 구현해야 함)와, 매핑 없음 진단 및 편집기 자동 완성이 제시하는 후보 목록입니다. Recipe의 implements:가 매핑된 타입과도, 그 어떤 기반과도 일치하지 않는 매핑 항목은 매핑, Recipe, 그리고 그 implements: 값을 밝히며 빌드를 중단시킵니다. components.type 키가 그 키가 지정하지 않은 버전의 컴포넌트 인스턴스에 적용되는 경우(버전 없이 작성된 키라면 모든 인스턴스), 검사는 해당 인스턴스 자체의 타입으로, 빌드가 그것을 컴파일하는 버전에서 다시 수행되며, 이를 만족하지 않는 Recipe는 마찬가지로 인스턴스를 밝히며 빌드를 중단시킵니다.
implements: 바인딩은 “같은 Component 타입, 프로바이더마다 다른 Recipes”를 가능하게 하는 메커니즘입니다. core/postgres Component는 helm 프로바이더용으로 이를 구현하는 Recipe 하나와 compose 프로바이더용으로 이를 구현하는 다른 Recipe를 가질 수 있습니다. 각 Recipe는 같은 implements: 값을 선언하며, Release가 빌드에 사용하는 Manifest가 그 타입을 원하는 Recipe에 매핑합니다.
베이스를 대상으로 작성한 Recipe는 이를 확장하는 모든 것에 사용됩니다
implements:는 베이스를 지정하며, 베이스를 지정한 Recipe는 체인의 깊이와 관계없이 그 베이스를 확장하는 모든 Component의 구체적인 구현입니다. 따라서 extends로 만든 특수화에는 자체 Recipe가 필요 없습니다. 바로 이 점 때문에 게시된 래퍼를 적은 비용으로 사용할 수 있습니다. 래퍼를 게시하는 팀은 Component를 작성하고, 이를 배포하는 팀은 모든 대상에서 베이스의 Recipes를 재사용합니다.
여기서는 두 가지 사실이 동시에 성립하며, 둘은 별개입니다. 이 둘을 “특수화에는 아무것도 필요 없다”로 뭉뚱그려 이해하면 실패하는 Manifest를 작성하게 되고, 그 원인을 엉뚱한 파일에서 찾게 됩니다.
- Recipe는 매칭됩니다. Manifest 매핑의 타입 키와 매핑된 Recipe의
implements:사이의 일관성 검사는 Recipe가 매핑된 타입 자체 또는 그 타입이 확장하는 임의의 베이스를 구현하면 매핑을 허용합니다. 위의 세 가지 버전 형태는 타입 자체에 적용되는 것과 똑같이 베이스에도 적용됩니다.implements: core/base-server:^1.0.0을 선언한 Recipe는 베이스 버전이1.4.0인 특수화는 만족하지만, 베이스가2.0.0인 특수화는 만족하지 않습니다. - Manifest는 여전히 특수화 자체의 타입을 매핑해야 합니다. Recipe 선택은 정확한 매핑 키로 이루어집니다.
enterprise/labelled-server의 인스턴스에는 자체mappings.components.type항목이 필요하며,core/base-server용으로 작성된 항목을 상속하지 않습니다. 자체 항목이 없는 특수화는 베이스가 매핑되어 있더라도 매핑되지 않은 인스턴스 진단과 함께 중단됩니다.
따라서 특수화의 작성 비용은 Manifest 한 줄이며, 새 Recipe는 필요 없습니다.
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0매핑된 타입의 extends 체인을 탐색할 수 없으면(루프를 이루거나, 체인이 지정한 베이스가 카탈로그에 없는 경우) 빌드는 매핑이 아니라 그 체인 결함에서 중단됩니다. 매핑이 의존하는 체인이 해석되기 전에는 매핑을 판단할 수 없기 때문입니다. 이 검사는 이미 이 머신에 있는 Components, 즉 카탈로그 디렉터리에 있는 것과 로컬 아티팩트 캐시가 lockfile 고정으로 보유한 것만을 통해 체인을 탐색하며 레지스트리에는 조회하지 않습니다. 따라서 레지스트리에만 있는 베이스는 여기서 없는 것으로 간주됩니다. 이를 가져오는 것이 aggrega pull의 역할입니다. 베이스는 그것을 확장하는 모든 것의 의존성이므로, pull은 Release가 도달하는 모든 extends: 체인을 따라가며 어떤 카탈로그 디렉터리에도 없는 각 베이스를 가져와 lockfile에 고정하고, 이후의 빌드는 그곳에서 베이스를 찾습니다. Aggregate가 베이스의 인스턴스도 선언하지 않는 한, Manifest에는 베이스 자체를 위한 줄이 필요하지 않습니다.
Recipe 제안은 이 매칭 규칙보다 범위가 좁습니다. 매핑 없음 진단이 출력하는 후보 목록과 에디터 자동 완성이 매핑 값에 적용하는 순서는 요청된 타입 자체를 구현하는 recipe를 제시하며, 그 베이스 중 하나를 구현하는 recipe까지 넓히지 않습니다.
실행 가능한 종단 간 안내(카탈로그에 게시된 래퍼, 이를 사용하는 Manifest 한 줄, 렌더링 출력을 구성하는 베이스의 Recipe, 자체 매핑이 없는 래퍼 인스턴스가 일으키는 중단)는 예제 examples/extends-wrapper/를 참조하십시오.
엔터티 간 버전 소비
모든 Aggrega 엔터티 종류(Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary)는 동일한 SemVer 정규식(architecture/02-ecosystem-philosophy.md에 따른 MAJOR.MINOR.PATCH)으로 검증되는 필수 metadata.version 필드를 가집니다. 버전의 형태는 균일하지만, 버전의 소비 방식은 엔터티 종류마다 다릅니다. 어떤 버전은 해석에 능동적으로 참여하고, 어떤 버전은 컴파일러가 대조하지 않는 서술적 출처 정보입니다. 아래 표는 라이브러리가 아닌 종류를 다루며, 컴파일러가 각 엔터티의 버전 필드로 무엇을 하는지를 밝히고 10-status.md의 네 가지 레이블 상태 분류를 사용해 각 소비 체계를 분류합니다. 네 가지 라이브러리 종류는 체계가 균일하면서도 다르기 때문에 표에서 제외됩니다. 소비자는 라이브러리를 이름만으로 참조하고, 선택적으로 :<version> 최소 버전 하한을 지정할 수 있으며, 해석된 버전과 그 콘텐츠 다이제스트는 Release별 lockfile이 소유합니다.
| 엔터티 | 소비 체계 | 상태 |
|---|---|---|
| Component | 타입 참조 해석, Recipe implements: 매칭 | available — 두 경우 모두 정확, 캐럿 범위(^MAJOR.MINOR.PATCH), 버전 없는 형식 지원(버전 해석 및 상태 → 버전 매칭 참조) |
| Feature | 연결 참조 해석, FeatureRecipe implements: 매칭 | Component와 동일 |
| Recipe | Manifest 매핑 계층 해석 | available — 매핑 값의 정확, 캐럿 범위, 버전 없는 형식이며, 각각 조건을 만족하는 가장 높은 버전을 선택함 |
| FeatureRecipe | Manifest 매핑 계층 해석 | Recipe와 동일 |
| Aggregate | 상위 aggregates[].type 참조 해석 | available — 정확, 캐럿 범위, 버전 없는 형식 각각이 조건을 만족하는 가장 높은 버전을 선택(버전 해석 참조) |
| Plugin | recipe.spec.capability → spec.provider.capabilities를 통한 Provider 디스패치 | available — 이름만 있는 capability가 provider를 선택하고, 그에 붙인 고정(helm:<version>, helm:^<version>)이 해당 플러그인의 어느 버전이 렌더링할지를 선택합니다. 플러그인의 식별자는 다이제스트 없는 oci://<repository> 참조와 metadata.version이며, 콘텐츠 다이제스트는 빌드가 가져온 바이트를 검증하는 데 사용하는 release lockfile에 기록됩니다 |
| Manifest | IR 그래프 출처(manifest_version) | available (출처 정보로만 읽히며 해석 디스패치에서는 역할 없음) |
| Release | IR 그래프 출처(release_version) + 템플릿 메타데이터(.metadata.release_version) | Manifest와 동일 |
카탈로그 해석 체계(Component, Feature, Aggregate, Plugin). 이들 종류에 대한 참조(component의 type, feature 연결의 type, 하위 aggregate 가져오기의 aggregates[].type, 파이프라인 단계의 plugin)는 버전 해석이 설명하는 규칙에 따라 해석됩니다. 정확, 캐럿 범위 또는 버전 없는 참조는 카탈로그가 보유한 버전 중 조건을 만족하는 가장 높은 버전을 선택하며, pull, 빌드, validate, 편집기, 어시스턴트용 도구가 모두 이 하나의 규칙을 똑같이 적용합니다. Component나 Feature의 경우 implements: 매칭은 같은 세 가지 형식을 반대 방향에서, 즉 구체적인 타입 버전을 Recipe나 FeatureRecipe가 선언한 형식과 대조하여 읽으며, 이는 선택이 아니라 아래에서 설명하는 일관성 검사로 이루어집니다. Provider 렌더링 플러그인 디스패치는 더 단순한 형태를 사용합니다. 이름만 있는 recipe.spec.capability를 provider 렌더링 플러그인의 spec.provider.capabilities에서 이름으로 조회하며, capability에 작성된 버전 고정은 해당 플러그인의 어느 버전이 렌더링할지를 선택하고, 이를 만족하는 버전이 없으면 중단합니다.
Manifest 매핑 계층 해석. Manifest의 평탄한 mappings.{components,features} 해석 메커니즘(name 및 type 계층, 이름이 타입보다 우선, 버전이 있는 타입이 버전 없는 타입보다 우선)은 entities/manifest.md에 문서화되어 있습니다. 리졸버는 이 매핑을 소비합니다. Recipe와 FeatureRecipe 선택은 매핑 값을 lockfile과 카탈로그에서 직접 조회하는 것이며, 타입에 매핑이 없는 component나 연결은 빌드를 중단시킵니다. spec.implements는 Recipe를 선택하지 않습니다. 이는 작성자가 이미 작성한 매핑에 대한 로드 시점 일관성 검사이자, no-mapping 진단과 편집기 자동 완성이 제시하는 후보 목록의 출처입니다. 이후 capability 디스패치는 Manifest의 구조적 형태가 아니라 해석된 Recipe의 spec.capability 필드에서 이어집니다.
서술적 출처 체계(Manifest, Release). Manifest metadata.version과 Release metadata.version은 컴파일러가 출처 정보를 채울 때 읽히며, IR 그래프의 출처 블록에 manifest_version과 release_version으로 나타납니다. 렌더링된 출력의 어떤 레이블에도 둘 중 어느 것도 담기지 않습니다. 템플릿에서도 Release 버전이 .metadata.release_version으로 노출됩니다. 두 버전 모두 해석 디스패치를 위해 다른 엔터티의 버전과 대조되지 않으며, 순수한 출처 정보입니다.
표 읽는 법. 네 가지 레이블 분류는 “버전 필드가 스키마에서 허용되고 엔터티에 존재한다”(항상 참 — 균일한 SemVer 정규식)와 “컴파일러가 해석 중에 이 버전과 대조한다”(엔터티마다 다름)를 구분합니다.
스키마 브리지 교차 필러 파이핑: 의도와 인프라의 연결
Aggrega는 Domain 1과 Domain 4 사이의 강한 관심사 분리를 표현합니다. Developer는 values 블록에 인지적 로직을 작성하고, Operator는 infra 블록에서 물리적 크기를 결정합니다. Aggregate.yaml 스키마는 이에 따른 구체적인 귀결 하나를 강제합니다. infra 키워드는 Aggregate의 컴포넌트 인스턴스와 그 features 첨부에 존재하지 않으며, additionalProperties: false와 결합되어 스키마 검증에서 거부됩니다. Developer는 Developer Intent 안에서 물리적 크기를 결정해서는 안 됩니다. 특정 값이 애플리케이션의 사례에 맞는 경우(예: 하드코딩된 포트나 특정 CPU 수), Architect는 이를 Component의 schema: 선언에서 명시적으로 노출할 수 있으며, 그 값은 values를 통해 전달됩니다.
특정 인프라 제약이 컴포넌트 계약의 본질적인 일부인 경우(10,000 프로비저닝 IOPS가 반드시 필요한 고처리량 트레이딩 데이터베이스, 정확히 4개의 GPU에서 실행되어야 하는 ML 워크로드 등), Platform Architect는 스키마 브리지 교차 필러 파이핑 패턴을 사용하는 전용 Component를 통해 그 제약을 노출합니다.
인프라를 인식하는 컴포넌트를 위한 스키마 브리지 패턴.
Component는 schema: 선언을 통해 개발자의 values 블록 안에 특정 인프라 다이얼을 노출하고, 바인딩된 Recipe의 valuesMapping: 템플릿은 그 값을 렌더링된 infra: 형태의 출력으로 전달합니다. 그 결과 인지적 의도와 물리적 크기 사이에 타입이 지정된 브리지가 생깁니다. 개발자는 검증된 필드를 통해 하드웨어 제약을 지정하고, 그 제약은 어느 쪽도 원시 인프라 코드를 작성하지 않고 Ops에 전달됩니다. 다이얼은 필러 키이므로 그 계약을 소유하는 Component에 선언됩니다. 베이스를 extends:하는 Component는 필러 키를 선언하지 않으므로 새 필러 키를 도입할 수 없습니다.
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safely다중 환경 스케일링(파라미터 호이스팅 요구 사항).
개발자의 Aggregate.yaml을 변경하지 않고 이 하드웨어 제약을 GitOps 환경(Dev와 Prod) 전반에 걸쳐 조정하기 위해, 개발자는 값을 타입이 지정된 parameters 계약으로 호이스팅합니다. Ops는 환경별 Release 파일을 통해 특정 IOPS 요구 사항을 충족합니다. 컴파일러의 실행 순서가 이 흐름을 보호합니다. 파라미터 계약 검증은 해석 단계에서 실행되고, 보간은 파라미터를 주변의 values: 문자열로 해석하며, Recipe의 valuesMapping: 템플릿은 해석된 값을 렌더링된 출력으로 전달합니다.
1. Developer Intent(다이얼의 추상화).
Developer는 IOPS를 제어해야 한다는 것을 알지만, 타입이 지정된 parameters 계약을 통해 구체적인 숫자를 환경 수준으로 추상화합니다.
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. GitOps Releases(Ops의 충족).
Ops는 환경별 Release 파일에서 parameters 계약을 충족합니다. 타입이 지정된 계약은 보간이 실행되기 전에 Release가 제공한 각 값을 검증합니다.
- Dev 환경(
release-dev.yaml):env_iops: 1000 - Prod 환경(
release-prod.yaml):env_iops: 25000
컴파일 순서. 이 메커니즘은 해석 단계에서 컴파일러의 엄격한 실행 순서에 의해 보호됩니다.
- 파라미터 계약 검증. Release가 제공한 각 파라미터 값은 Aggregate의 타입이 지정된
parameters:선언에 대해 검증됩니다. Prod 값25000은 검증을 통과하며(min: 1000, max: 100000범위 내),500이라는 값은 명확한 오류와 함께 중단됩니다. - 보간. 컴파일러는 Prod
Release의 파라미터 값을 읽고25000을AggregateYAML 문자열의values.required_iops위치에 보간합니다. 병합된 파라미터 맵은 렌더링 동안 유지되므로 경로 템플릿 표면은.parameters.<slot>을 직접 읽을 수 있으며, 값 템플릿 표면은 Aggregate의values:블록에 이미 기록된 보간 후 리터럴을 사용합니다. 맵은 모든 렌더 단계가 완료될 때까지 읽을 수 있으며, 해당 맵이 해석된 컴파일에서만 접근할 수 있습니다. - 스키마 검증. Component의
schema:선언은 결과로 나온values:딕셔너리를 검증합니다.values.required_iops: 25000은 스키마의min: 1000, max: 100000을 충족합니다. - Recipe valuesMapping 렌더링. 바인딩된 Recipe의
valuesMapping:템플릿은values.required_iops를 프로바이더의infra형태 출력(iops: 25000)으로 전달합니다. Wasm 프로바이더 플러그인은 올바른 물리적 데이터베이스 구성을 생성합니다. 개발자는 명시적인 하드웨어 제어를, Ops는 환경별 스케일링을 얻으며,Aggregate는 기능에 구애받지 않는 상태로 유지됩니다.