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

Manifest

Manifest 엔티티의 개념적 역할(Domain 4 — 추상 인터페이스를 구체적인 Recipes에 바인딩하는 매핑 테이블)은 architecture/04-entity-taxonomy.md에서 다룹니다. 이 페이지는 Manifest 작성 영역을 다룹니다. Release와 함께 어떻게 배치되는지, 플랫 URI 매핑 형태, extends를 통한 구성, URI 축약 규칙, 어노테이션 기반 Feature 바인딩, 그리고 플랫폼이 예약한 aggrega.ai/ 접두사를 설명합니다.

Manifest와 Release: 관심사 분리

Manifest와 Release는 서로 겹치지 않는 책임을 집니다.

  • Manifest는 각 카탈로그 타입을 어떤 Recipe가 실현하는지, 그리고 그 Recipe의 spec.capability를 통해 이를 렌더링하는 provider(예: Helm, Helm-chart, Compose)를 지정합니다. Manifest는 매핑 테이블로, 각 추상 인터페이스를 어떤 구체적인 Recipe가 구현하는지를 프로젝트별로 Git에 커밋하여 기록한 것입니다. 빌드가 그 Recipes에 요구하는 버전과 다이제스트는 각 Release의 lockfile에 별도로 고정됩니다.
  • Release는 목적지(예: GitOps 아티팩트 생성을 위한 물리적 출력 폴더)를 지정합니다. Release는 배포 라우터로, 컴파일된 아티팩트가 어디에 놓이는지를 환경별로 기술한 것입니다.

Release 스키마에는 어떤 중첩 수준에도 provider 필드가 없습니다. provider 디스패치는 오로지 Manifest에 속합니다.

컴파일 경로. 사용자가 aggrega build --release release.yaml을 실행하면 컴파일러는 두 소스를 결합하여 물리적 아티팩트를 결정합니다.

  1. 목적지 읽기. 컴파일러는 Release의 boundary를 스캔합니다. 예를 들어 boundary ovh-cluster-3에는 component user-db(type: core/postgres:1.0.0)가 포함되어 있습니다.
  2. Manifest 스캔. 컴파일러는 Release가 manifest: 필드로 가리키는 Manifest를 엽니다.
  3. 2단계 조회. 먼저 name 계층에서 "user-db"를 확인합니다. 찾지 못하면 type 계층에서 "core/postgres:1.0.0"(버전 지정)을, 이어서 "core/postgres"(버전 미지정)를 확인합니다.
  4. Recipe 결정. 일치하는 항목의 값은 Recipe URI이며, 그 URI가 가리키는 Recipe는 spec.capability에 어떤 provider가 자신을 렌더링하는지 선언합니다.
  5. 출력 생성. 이제 컴파일러는 대상 폴더(dist/boundaries/ovh-cluster-3/), provider(Wasm을 통한 Helm 렌더링), 아티팩트(Recipe의 소스 코드)를 알게 됩니다. AOT(ahead-of-time) GitOps 경계가 처음부터 끝까지 지켜집니다.

플랫 URI 매핑

Manifest의 mappings: 블록은 컴포넌트 타입 URI에서 Recipe URI로(그리고 기능 타입 URI에서 FeatureRecipe URI로) 이어지는 플랫 맵입니다. 매핑은 Manifest 수준에서 capability에 구애받지 않으며, capability 결정은 Manifest의 구조적 형태가 아니라 렌더링 시점에 해석된 각 Recipe의 spec.capability 필드에서 이루어집니다. 이 블록은 매핑을 두 개의 최상위 키 아래에 구성합니다:

  • **components.type**은 컴포넌트 타입 URI를 Recipe URI에 매핑합니다. 선언된 타입의 모든 컴포넌트 인스턴스는 지정된 Recipe로 해석됩니다. 매핑은 컴포넌트 타입마다 일대일입니다. 인스턴스의 정확한 타입을 지정하지 않는 키라도, 그 정확한 타입을 지정하는 키가 없고 같은 기반에 대해 다른 키가 작성되지 않았다면 타입의 기반을 통해 그 인스턴스에 도달합니다. 따라서 버전 없이 작성된 키(core/postgres)나 다른 버전을 지정하는 키(core/postgres:1.0.0)가 core/postgres:2.0.0의 인스턴스에 도달할 수 있습니다. 다만 그 키가 지정하는 Recipe는 그러한 각 인스턴스 자체의 버전을 구현해야 합니다. 이렇게 도달하여 implements: core/postgres:1.0.0을 선언한 Recipe에 매핑된 core/postgres:2.0.0의 인스턴스는 빌드를 중단시킵니다. 그러한 인스턴스는 그 버전을 지정하는 키(core/postgres:2.0.0)로 그것을 구현하는 Recipe에 매핑하십시오.
  • **features.type**는 기능 타입 URI를 FeatureRecipe URI에 매핑합니다. 선언된 타입의 모든 Feature 첨부는 지정된 FeatureRecipe로 해석됩니다. 자격 증명 Features(feature.aggrega.ai/kind: secret 레이블이 붙은 것)는 운영 Features와 같은 features.type 맵에 있습니다. 이것이 통합된 Feature 엔터티 모델입니다.

각 블록은 type과 함께 name 계층도 받으며, 이 계층은 특정 인스턴스 이름을 Recipe(또는 FeatureRecipe) URI에 매핑합니다. name 계층은 type 계층보다 우선합니다. components.name에 이름이 지정된 인스턴스는 해당 Recipe로 해석되고, 같은 타입의 다른 모든 인스턴스는 components.type을 통해 해석됩니다. 이는 인스턴스별 재정의를 표현합니다. 한 컴포넌트 타입의 두 인스턴스가 컴포넌트 타입을 분기하거나 Manifest를 복제하지 않고도 서로 다른 두 Recipes를 통해 배포될 수 있습니다(예를 들어 대부분의 데이터베이스 인스턴스는 일괄 매핑된 Recipe를 사용하고, 한 인스턴스만 다른 물리적 구현에 고정되는 경우). 재정의는 일관되게 적용됩니다. 이름이 지정된 인스턴스는 재정의 Recipe를 통해 렌더링되고 소스도 그 Recipe에서 고정합니다. features.name은 Feature 첨부를 위한 대칭적인 계층이며, 첨부 자체의 이름, 즉 컴포넌트의 features:에서 그것이 작성된 키를 키로 사용하고, 첨부된 컴포넌트의 이름을 키로 사용하는 일은 결코 없습니다. 인스턴스별 recipe 재정의 예제에서 최소한의 두 인스턴스 사례를 처음부터 끝까지 살펴봅니다.

연결이 지니는 첨부는 소비하는 컴포넌트에서 갖는 이름을 키로 사용합니다. 즉 <alias>.<slot>으로, 연결이 작성된 별칭, 점, 그리고 첨부가 채우는 슬롯입니다(Aggregate의 연결 항목 참조). 따라서 한 연결의 자격 증명은 같은 타입의 다른 모든 첨부와 다르게 실현될 수 있습니다:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

이 항목은 다음 단락에서 설명하듯 다른 name 계층 항목과 마찬가지로 고정되고 검증됩니다. 첨부가 지정하는 Feature 역시 컴포넌트 자체에 작성된 첨부의 Feature와 정확히 같은 방식으로, 작성자가 작성한 연결 항목 아래에서 고정되고 검증됩니다. 잠금 파일을 참조하십시오.

name 키는 빌드에 있는 것을 지정해야 합니다. 이 계층은 정확한 이름으로 일치시키므로, 빌드의 컴포넌트 인스턴스가 아닌 components.name 키나 빌드의 첨부가 아닌 features.name 키(대부분 첨부 자체의 이름이 들어가야 할 자리에 첨부가 놓인 컴포넌트의 이름을 쓴 경우)는 아무것도 참조하지 않으며, 그 키가 대상으로 삼은 인스턴스는 조용히 type 계층을 통해 해석됩니다. 대신 빌드는 어떤 것도 렌더링되기 전에 그러한 키에서 중단되며, Manifest, 키, 빌드에 실제로 있는 그 종류의 이름, 그리고 아마 의도했을 이름을 명시합니다. A Manifest name mapping names nothing in the build (Manifest 매핑이 빌드의 어떤 것도 지정하지 않음)을 참조하십시오.

이름으로 바인딩된 실현은 타입으로 바인딩된 실현과 똑같이 고정되고 검증됩니다. aggrega pull은 어느 계층이든 바인딩하는 모든 Recipe와 FeatureRecipe를 카탈로그 디렉터리, 캐시 또는 레지스트리에서 가져오고, 각각을 해석된 버전 및 콘텐츠 다이제스트와 함께 이를 바인딩하는 매핑 항목 아래에 Release의 잠금 파일에 기록합니다. name 계층 항목은 manifest.spec.mappings.components.name.<instance>, type 계층 항목은 그 옆의 manifest.spec.mappings.components.type.<type>입니다. aggrega build는 이들 모두를 각자의 고정 값에 맞춥니다. Manifest가 바인딩하는 실현에 대한 행을 기록하지 않은 잠금 파일은 오래된 것으로 간주되어 빌드를 중단시키며, 해당 실현과 이를 바인딩하는 항목을 명시합니다. pull 이후 콘텐츠가 변경된 실현도 같은 방식으로 빌드를 중단시키며, 두 다이제스트를 모두 명시합니다. 두 경우 모두 aggrega pull --release <release>가 실현을 현재 상태대로 기록합니다. type 항목과 마찬가지로 name 항목은 Release가 그 이름의 인스턴스를 선언하는지와 무관하게 고정되므로, 어떤 카탈로그나 레지스트리에도 없는 Recipe를 지정하는 name 항목은 pull을 중단시킵니다. 빌드에 있는 어떤 인스턴스도 지정하지 않는 name 항목도 고정되며, 위 단락에서 설명한 대로 빌드를 중단시킵니다.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

렌더링 시점의 capability 결정. Manifest 항목은 컴포넌트 타입을 Recipe URI에 바인딩합니다. Recipe URI는 최대 두 개의 세그먼트, 즉 선택적인 선행 capability와 그 뒤의 recipe 이름, 그리고 선택적인 :version을 가집니다. 리졸버는 첫 번째 /에서만 분할하므로, 세 번째 세그먼트가 있는 참조는 어떤 recipe도 지정하지 않으며 해석을 중단시킵니다. 렌더링 시점에 리졸버는 잠금 파일과 카탈로그에 대한 직접 URI 조회로 Recipe를 로드하고, 각 Recipe의 spec.capability 필드가 (경로, capability)별 디스패치 그룹을 결정합니다. 더 넓은 카탈로그가 지원하는 Providers의 수와 무관하게 Manifest의 구조적 형태는 플랫하게 유지됩니다.

직접 URI 조회

Manifest의 매핑 값은 Recipe URI입니다. 컴파일러는 잠금 파일과 카탈로그에 대해 URI를 직접 해석하여 일치하는 Recipe를 반환합니다. 컴파일러는 컴포넌트 타입을 “구현하는” Recipe를 찾기 위해 spec.implements 선언을 순회하지 않습니다. 각 Manifest 항목은 개발자가 작성한 컴포넌트 타입을 특정 Recipe URI에 바인딩하며, 그 선택은 Manifest 내용에서 명시적이고 모호하지 않습니다.

spec.implements는 매핑 테이블에 대한 일관성 검사입니다. 해석된 Recipe의 spec.implements 값은 해당 매핑 항목에 대한 Manifest의 컴포넌트 타입 키와 일치해야 합니다(MUST). 또는 그 키가 체인의 어느 깊이에서든 extends하는 기반과 일치해야 합니다. 기반을 대상으로 작성된 Recipe는 그것을 확장하는 모든 것을 구현하기 때문입니다. 어느 쪽과도 일치하지 않는 값은 Manifest 항목, 해석된 Recipe, 충돌하는 spec.implements 값을 명시하는 명확한 진단과 함께 OPS_ERROR를 발생시킵니다. 이 검사는 Manifest 매핑 항목마다 한 번, 구성된 Manifest에 대해 어떤 Recipe도 해석되기 전에 실행됩니다. 정적이고 결정적이며, 매핑된 타입 자체의 extends 체인 외에는 아무것도 순회하지 않습니다. components.type 키가 그 키가 지정하지 않은 버전의 컴포넌트 인스턴스에 도달하면, 해당 인스턴스에 대해 같은 방식으로 한 번 더 판정되며, 이때 키의 자리에는 빌드가 그 인스턴스를 컴파일하는 버전의 인스턴스 자체 타입이 놓입니다. 이는 플랫 URI 매핑에서 설명합니다. 기반의 Recipe가 특수화에 무엇을 덜어 주고 무엇을 덜어 주지 않는지는 ../vocabulary/inheritance-and-interface.md를 참조하십시오.

Release의 의존성을 읽는 모든 명령이 이 검사를 실행하며, 각 명령은 발견 사항이 무엇을 의미하는지 스스로 결정합니다. aggrega build와 aggrega pull은 둘 다 이후에 사용할 무언가를 생성하므로 중단하고, aggrega validate와 aggrega lint는 다른 발견 사항과 함께 이를 보고하고 0이 아닌 코드로 종료하며, 편집기는 이를 다른 진단들 가운데 하나로 게시합니다. 인스턴스에 대한 판정에서는 aggrega lint가 예외입니다. 이 명령은 매핑 항목을 판정할 뿐 그 항목이 도달하는 인스턴스는 판정하지 않으므로 이를 보고하지 않지만, aggrega build, aggrega pull, aggrega validate --release는 보고합니다. 진단과 해결 방법은 ../errors/fatal-halts.md를 참조하십시오.

일관성 검사는 extends 체인을 읽는 유일한 매핑 표면입니다. Recipe 선택은 매핑 키에 대해 여전히 정확히 일치해야 합니다. 매핑된 기반을 확장하는 컴포넌트 타입도 여기에 자체 항목이 필요하며, 상속으로 항목을 얻지 않습니다.

spec.implements는 후보도 제안합니다. 타입에 Manifest 매핑이 없는 인스턴스는 OPS_ERROR로 빌드를 중단시키며, 이 오류는 spec.implements가 해당 타입을 구현할 수 있는 recipe들을 고정 후보로 나열합니다. 매핑 값에 대한 편집기 자동 완성도 같은 일치 recipe들을 가장 먼저 순위에 올립니다. 두 표면 모두 요청된 타입 자체에 대해 spec.implements를 읽으므로, 그 타입의 기반 중 하나를 구현하는 recipe는 매핑이 일관된 것으로 판정되더라도 후보로 제시되지 않습니다. 따라서 spec.implements는 recipe가 무엇을 구현할 수 있는지 선언하고 일관성 검사, 매핑 없음 진단, 자동 완성에서 사람의 선택에 정보를 제공하지만, 빌드를 해석하지는 않습니다. Manifest 매핑은 재현성을 위해 잠금 파일에 고정되는 사용자의 명시적인 배포 선택이며, 카탈로그는 사용자를 대신해 배포를 선택하지 않습니다.

URI 버전 세그먼트의 세 가지 형식

Manifest의 Recipe URI는 다음 세 가지 형식 중 하나로 버전을 지정할 수 있습니다.

  • 정확한 버전 — helm/postgres:1.2.0. lockfile은 정확히 이 버전을 고정해야 합니다. lockfile을 처음 해석할 때 리졸버는 이 버전을 고정하며, 해석 시점에 카탈로그나 레지스트리에 이 버전이 없으면 워크스페이스 로드가 오류와 함께 중단됩니다.
  • 범위 — helm/postgres:^1.2.0. 표준 MVS 규칙을 따르는 Semver 범위입니다. lockfile을 처음 해석할 때 리졸버는 범위를 만족하는 사용 가능한 가장 높은 버전을 고정합니다.
  • 버전 없음 — helm/postgres. :version 접미사가 없습니다. lockfile을 처음 해석할 때 리졸버는 사용 가능한 최신 버전을 고정합니다.

이후 빌드는 사용자가 입력한 형식과 관계없이 lockfile에 고정된 버전을 사용합니다. 더 새로운 버전으로 다시 해석하려면 사용자의 명시적인 조치가 필요합니다. aggrega pull --upgrade --release <release> <uri>는 다른 모든 고정을 유지한 채 단일 의존성을 다시 해석하고, aggrega pull --upgrade --release <release>는 전부를 다시 해석합니다. lockfile은 빌드의 기준 정보이며, 사용자가 입력한 형식은 작성 시점에 사용자가 버전 제약을 표현하는 방법입니다.

capability로 한정된 참조

카탈로그에서 Recipe의 식별자는 capability 범위로 구분됩니다. 두 recipe는 서로 다른 spec.capability 값을 선언하면서 같은 metadata.name과 버전을 공유할 수 있습니다. 레지스트리 식별자는 recipe의 kind, spec.capability(그것이 가진 버전 고정은 제외), 이름에서 도출되는 recipe/{capability}/{name}:{version}이며, 표준 라이브러리 카탈로그 트리는 관례에 따라 이 좌표를 recipe/{capability}/{name}/에 그대로 반영합니다. Manifest 매핑 값은 다음 두 가지 정밀도 중 하나로 recipe를 지정합니다.

  • 단순 이름 — mariadb:1.0.0. 카탈로그에서 해당 이름을 가진 recipe가 정확히 하나일 때 해석됩니다. 실제로 가장 많이 쓰이는 형식입니다.
  • capability 한정 — compose/mariadb:1.0.0. 첫 번째 / 앞의 세그먼트가 recipe의 spec.capability를 버전 고정 없이 지정합니다. 참조에 버전 고정을 쓰면 거부됩니다(E0095). 둘 이상의 recipe가 같은 이름을 제공할 때 필요합니다. 두 recipe와 일치하는 단순 참조는 모호하므로, 조용히 하나를 고르지 않고 해석 단계에서 명시적으로 중단됩니다.

Recipe URI에는 그 밖의 위치가 없습니다. 리졸버는 첫 번째 /에서만 분할하므로 compose/mariadb는 capability compose와 recipe mariadb를 지정하며, 세그먼트가 세 개인 참조는 어느 정밀도에서도 recipe와 일치하지 않습니다.

위의 버전 세그먼트 형식은 두 형태 모두에 적용됩니다.

매핑에서 레지스트리에 게시된 엔티티

로컬 카탈로그가 아닌 레지스트리에서 가져오는 엔티티는 로컬 엔티티와 정확히 같은 식별자로 참조됩니다. 참조에는 레지스트리 호스트도, 엔티티 kind 세그먼트도 포함되지 않습니다. 리졸버가 아래의 Context-Aware Shorthand URIs 규칙에 따라 둘 다 제공합니다. 호스트는 워크스페이스에 구성된 기본 레지스트리에서, kind 세그먼트는 스키마에서 참조가 놓인 위치에서 가져옵니다. 로컬 카탈로그 디렉터리와 캐시 어디에도 사본이 없으면 aggrega pull(또는 --auto-pull로 실행한 빌드)이 도출된 위치에서 엔티티를 가져와 캐시하고, 해석된 버전과 콘텐츠 다이제스트를 lockfile에 고정합니다. 이후 빌드는 네트워크 접근 없이 캐시를 사용합니다.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

호스트와 엔티티 kind 세그먼트는 작성되는 것이 아니라 도출되므로, 둘 중 하나를 참조에 써 넣으면 게시된 엔티티를 가리키지 못하고 어떤 카탈로그 항목에도 없는 식별자가 만들어집니다. Component 또는 Feature 참조는 엔티티가 로컬 카탈로그, 캐시, 레지스트리 중 어디에서 해석되든 metadata.name 그대로에 선택적인 :version을 더한 것입니다. 비공개 레지스트리를 사용하는 워크스페이스는 각 참조가 아닌 자체 구성에서 해당 호스트를 지정합니다.

완전성 검사

모든 매핑이 해석된 후, 컴파일러는 개발자의 Aggregate에 있는 모든 component 및 attachment 인스턴스(자격 증명 Feature도 다른 것과 같은 attachment입니다)에 해석된 Recipe 또는 FeatureRecipe가 있는지 확인합니다. 매핑되지 않은 엔티티가 있으면 치명적 중단이 발생하며, 누락된 엔티티를 모두 나열하고 공백을 메우기 위해 추가할 components.type 또는 features.type 키를 제안하는 명시적인 진단이 출력됩니다.

DRY Manifest를 위한 YAML 앵커

대규모 매핑 집합에서 YAML이 비대해지는 것을 피하기 위해, Manifest는 표준 YAML 앵커(&와 *)를 위한 선택적 defs: 블록을 지원합니다.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature 협상

capability 핸드셰이크는 동일한 플랫 URI 매핑을 사용합니다.

  1. 개발자는 Aggregate에서 component에 core/data-masking을 연결하며, 해당 component의 features: 맵에서 고유한 이름을 붙입니다.
  2. 컴파일러는 Manifest의 features.type 맵에서 core/data-masking을 조회합니다.
  3. 조회 결과가 FeatureRecipe URI(예: helm/data-masking-litellm:1.0.0)로 해석되면 해당 capability가 존재하는 것이며, FeatureRecipe의 파이프라인이 정의된 순서대로 실행됩니다.
  4. features.type에 일치하는 항목이 없으면 컴파일러는 빌드를 중단하고 매핑되지 않은 Feature를 나열합니다.

Manifest는 features.annotations 블록도 받습니다. 이는 Release 또는 Aggregate 하위 시스템이 component별 선언 대신 annotation 키로 Features를 연결할 수 있게 하는 병렬 작성 표면입니다. 바인딩 형태, 어떤 작성 표면이 어떤 라우팅 경로를 사용하는지 결정하는 side 대 pillar 구분, 명시적 연결 우선 원칙, 스키마 기본값 규칙은 아래의 전용 Annotation-Driven Feature Bindings 섹션에서 다룹니다.

extends를 통한 합성

Manifest는 mappings를 상속받을 기본 Manifest를 가리키는 단일 extends: 참조를 선언할 수 있습니다. 이 참조는 URI가 아니며 카탈로그를 통해 해석되지 않습니다: Manifest는 배포 측에 속하며 게시되지 않고 Release 옆에서 작성되므로, 값은 Manifest 파일에 대한 상대 경로(./base-manifest.yaml)이거나 Release 자체 디렉터리에 있는 Manifest의 단순 metadata.name입니다. 상대 경로는 워크스페이스 안의 Manifest를 가리켜야 합니다. 또는 Release가 워크스페이스 밖에서 지정된 경우(명령줄 또는 워크스페이스 구성에서)에는 해당 Release가 있는 디렉터리 안을, 워크스페이스 밖에서 명령줄로 단독 지정한 Manifest의 경우에는 그 Manifest가 있는 디렉터리 안을 가리켜야 합니다. 상위로 벗어나거나 심볼릭 링크를 통해 밖으로 나가는 경로는 해당 파일을 읽기 전에 거부됩니다(errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (다른 파일에 대한 참조가 머물러야 할 디렉터리 밖으로 나갑니다)” 참조). 키가 충돌하면 자식 매핑이 기본 매핑을 덮어쓰므로, 전체를 복사해 작성하지 않고도 환경 오버레이 패턴(환경별로 정밀한 차이만 둔 staging/prod 동등성)과 로컬 개발 패턴을 지원합니다.

병합 의미론. 로컬 Manifest가 기본 Manifest를 확장하면, 컴파일러는 계층별로 얕은 키 교체를 수행합니다. type과 name 딕셔너리는 깊은 병합 없이 각각 독립적으로 병합되며, 이로써 O(1) 딕셔너리 조회가 보장되고 상속 동작을 예측할 수 있게 됩니다. 각 계층 내에서는 자식 키가 부모 키를 덮어씁니다.

로컬 개발 브리지 패턴. extends의 일반적인 용도는 Aggregate를 건드리지 않고 로컬 프로토타이핑을 위해 자격 증명 FeatureRecipe를 교체하는 것입니다. 프로덕션에서는 기본 Manifest가 features.type 계층 아래에서 자격 증명 Feature core/aws-secrets-manager를 프로덕션 FeatureRecipe에 매핑합니다. 로컬 프로토타이핑을 위해 플랫폼 팀은 기본 Manifest를 확장하고 자격 증명 Feature 매핑을 정밀하게 재정의하여 host-env-injector를 사용하도록 하는 local-manifest를 제공합니다. 이는 자격 증명을 ${SECRET_NAME}과 같은 변수 참조로 Compose 파일에 전달하는 로컬 FeatureRecipe이며, Docker Compose는 스택이 시작될 때 이를 셸 환경 또는 .env 파일에서 치환합니다. 개발자는 표준 로컬 워크플로를 얻고, Aggregate는 프로덕션에서 기능에 구애받지 않는 상태로 유지됩니다.

컨텍스트 인식 축약 URI

Aggrega 컴파일러는 Manifests에서 OCI URI를 해석할 때 **컨텍스트 인식 추론(Context-Aware Inference)**을 사용합니다. 엔지니어가 정규화된 도메인 이름(FQDN)과 아키텍처 엔터티 유형을 생략하면, 컴파일러는 자동으로 기본 레지스트리(.aggrega-config.yaml에서 구성)로 대체하고 스키마에서 문자열이 위치한 곳을 기준으로 엔터티 유형을 추론합니다.

추론 규칙:

  1. 도메인 기본값: 도메인이 없는 URI(예: python-worker-helm:1.0)에는 구성된 default_registry(기본값: hub.aggrega.ai/)가 접두사로 붙습니다.
  2. 컨텍스트 기반 엔터티 확장: 컴파일러는 엄격한 스키마 사전을 기준으로 올바른 엔터티 경로를 덧붙입니다.
    • Aggregate.spec.components[].type 아래의 문자열은 /component/로 확장됩니다.
    • Aggregate.spec.aggregates[].type 아래의 문자열은 /aggregate/로 확장됩니다.
    • Manifest.spec.mappings.components.type 또는 Manifest.spec.mappings.components.name 아래의 문자열은 /recipe/로 확장됩니다.
    • Manifest.spec.mappings.features.type 또는 Manifest.spec.mappings.features.name 아래의 문자열은 /featurerecipe/로 확장됩니다. 여기에는 자격 증명 Features(feature.aggrega.ai/kind: secret 레이블이 붙은 것)도 포함되며, 이들도 같은 FeatureRecipe 경로를 사용합니다.
    • pipeline[].plugin에 할당된 문자열은 /plugin/으로 확장됩니다.
  3. 3계층 우선순위: OCI 추론을 적용하기 전에 컴파일러는 3계층 엔터티 해석 모델에 정의된 대로 워크스페이스의 카탈로그 디렉터리와 아티팩트 캐시(워크스페이스 및 캐시 계층)를 검색합니다. OCI 추론은 엔터티가 레지스트리 계층에 도달했을 때만 적용됩니다. 매핑 키나 값은 결코 파일 경로로 읽히지 않습니다. 로컬에서 작성된 Recipe나 FeatureRecipe는 카탈로그 디렉터리(워크스페이스 루트의 catalog/ 또는 workspace.catalog_dirs에 나열된 디렉터리)에 있으며, 그 참조로 지정됩니다.

축약형 사용 예:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

ops/ 접두사 없음. Recipe 이름에는 ops/ 접두사가 붙지 않습니다. OCI 분류 체계의 recipe/ 엔터티 유형 디렉터리가 이미 도메인을 식별하므로, Recipes는 추가 접두사 없이 recipe/{capability}/{name} 아래에 배포됩니다. Manifests는 Recipes를 {capability}/{name}으로, 또는 컨텍스트 인식 추론을 위해 이름만으로 참조합니다. 전체 OCI 분류 체계는 architecture/13-catalog-and-registry.md §6을 참조하십시오.

어노테이션 기반 Feature 바인딩

Manifest의 features.annotations 블록은 어노테이션 키와 Feature 타입 사이의 바인딩, 그리고 각 바인딩이 어노테이션 값을 전달하는 라우팅 경로를 선언합니다. 바인딩은 컴포넌트별로 반복되는 Feature 연결, 즉 하나의 경계에 걸친 수십 개의 컴포넌트가 각각 동일한 features: 블록을 갖는 패턴을 Release 경계나 Aggregate 하위 시스템의 단일 어노테이션 선언으로 압축하기 위한 작성 수단입니다.

스키마 형태:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

바인딩은 대상 Feature 타입을 지정하는 feature 필드와, 점으로 구분된 경로의 하위 키 라우트를 대상 축별로 묶는 maps 블록을 가집니다. feature 필드는 형제 섹션인 features.type(FeatureRecipe 버전 바인딩이 위치하는 곳)에도 나타나야 하는 Feature 타입을 참조합니다. maps 블록은 축을 키로 하는 두 목록인 maps.infra와 maps.values를 선언하며, 각 목록은 대상 Feature의 spec.schema.<pillar>.<path> 속성을 가리키는 점 구분 경로 문자열을 담습니다. 바인딩은 두 목록을 통틀어 최소 하나의 경로를 선언해야 합니다(JSON Schema가 maps에 minProperties: 1을 강제합니다).

동일한 annotation 키에 대한 Provider 다형성(예: feature.aggrega.ai/rewrite-host가 Kubernetes 배포에서는 core/k8s-dns-resolver에, 로컬 Compose 배포에서는 core/compose-bridge에 바인딩되는 경우)은 서로 다른 Manifests에서 서로 다른 Feature 타입을 선택하는 방식으로 표현합니다. 각 Manifest는 annotation을 하나의 Feature에 바인딩하며, 선택된 Feature의 FeatureRecipe가 provider별 구현을 담습니다.

측면-축 분할. Aggregate-as-Authoring-Surface 불변 조건은 각 작성 측면을 한 축의 라우팅 경로로 제한합니다. Aggregate 측 어노테이션은 maps.values 경로로만 라우팅되고, Release 측 어노테이션은 maps.infra 경로로만 라우팅됩니다. 두 축 모두에 경로를 선언한 바인딩은 측면 간 합성을 지원합니다. Aggregate 측 어노테이션은 values 축 부분 집합을 실행하고, 같은 키에 대한 Release 측 어노테이션은 infra 축 부분 집합을 실행하며, 두 기여는 (Component, Feature) 쌍마다 두 축이 모두 채워진 하나의 Feature 연결로 합성됩니다. 측면-축 불일치(예: maps.infra만 선언한 바인딩에 대한 Aggregate 측 어노테이션)는 어노테이션 키, 라우팅된 축, 작성 측면, 소스 위치를 명시하는 명확한 진단과 함께 빌드를 중단하며, 이 진단은 어노테이션 값이 작성된 문서의 도메인으로 분류됩니다.

경로 대상 검증. 카탈로그 로드 시 컴파일러는 maps.infra와 maps.values 아래에 선언된 모든 점 구분 경로가 대상 Feature의 spec.schema.<pillar>가 실제로 선언한 속성에 대응하는지 검증합니다. Feature 스키마에 없는 경로로 라우팅하는 바인딩은 바인딩, 대상 Feature, 라우팅된 축과 경로를 명시하는 명확한 OPS_ERROR와 함께 카탈로그 로드를 중단합니다. 단순한 속성 탐색으로 처리할 수 없는 스키마 형태($ref, patternProperties, oneOf / anyOf / allOf 합성)는 해당 분기에서 정적 검사를 종료하고, 불일치는 이후의 스키마 검증이 잡아내도록 맡깁니다.

어노테이션 값 형태. 바인딩은 세 가지 형태의 어노테이션 값을 받습니다. 스칼라: 단일 YAML 값(문자열, 숫자, 불리언)입니다. 두 축을 통틀어 정확히 하나의 경로를 선언한 바인딩과 짝지어진 스칼라는 값을 그 단일 경로로 라우팅합니다. 둘 이상의 경로를 선언한 바인딩과 짝지어진 스칼라는 모호한 라우팅이므로 명확한 진단과 함께 빌드를 중단하며, 이 진단은 어노테이션 값이 작성된 문서의 도메인으로 분류됩니다. 구조화: 최상위 하위 키가 각각 maps.infra 또는 maps.values 아래의 점 구분 경로 항목과 일치하는 YAML 맵입니다. 각 하위 키는 선언된 축으로 독립적으로 라우팅되며, 측면-축 분할은 하위 키별로 적용됩니다. 명시적 YAML null: 캐스케이드 범위에서 상속된 바인딩을 해제합니다(구조화 값 안의 하위 키별 null은 형제 키는 유지한 채 개별 하위 키만 해제합니다). 구조화 값에 대한 표준 작성 안내(하위 키별 캐스케이드 병합, 측면 간 합성, 하위 키별 타입 검증, 선언된 type이 없는 스키마 필드에 대한 완화된 기본 방식)는 providers/well-known-annotations.md §“Structured annotation values”를 참고하십시오.

키 충돌 시 명시적 연결 우선. Release 컴포넌트나 Aggregate 컴포넌트가 명시적 features: 항목과, 같은 Feature 키로 확장되는 어노테이션을 모두 가지면 명시적 항목이 유지되고 해당 컴포넌트에서 그 키에 대한 어노테이션 확장은 아무 작업도 하지 않습니다. 합성 연결은 작성자가 선언한 Feature 인스턴스를 절대 덮어쓰지 않습니다. 따라서 작성자는 대부분의 컴포넌트에 어노테이션 확장을 사용하고, 같은 키로 명시적 features: 항목을 작성해 개별 컴포넌트만 정밀하게 재정의할 수 있습니다. 명시적 항목은 컴포넌트별 사용자 지정을 담고, 어노테이션은 다른 모든 컴포넌트에 그대로 캐스케이드됩니다.

측면 간 합성에서 리프별 명시적 우선. 명시적 연결과 어노테이션 기여가 같은 Feature 인스턴스를 채우되 서로 다른 리프에 쓰는 경우, 두 기여가 모두 유지되며 결과 Feature는 각 리프의 출처를 기록한 리프별 출처 정보와 함께 두 리프를 모두 가집니다. 명시적 연결과 어노테이션 기여가 같은 축 안의 같은 리프를 대상으로 하면 명시적 기여가 우선하며, IR은 억제된 어노테이션 출처를 해당 리프의 재정의 표시로 기록합니다. 카탈로그 로드는 억제된 어노테이션 키와 소스를 명시하는 권고성 린트 경고로 빌드 시점에 이 재정의를 알립니다.

확장 시점의 스키마 기본값. 어노테이션 확장으로 생성된 합성 Feature 연결은 어노테이션 값이 바인딩의 선언된 경로를 통해 채우는 리프만 가집니다. 대상 Feature의 spec.schema에 선언된 스키마 기본값은 확장 시점에 합성 연결로 병합되지 않습니다. 기본값 구체화는 FeatureRecipe 렌더링 계층의 책임이며, 명시적 연결과 합성 연결에 동일하게 적용되므로 두 경로는 같은 유효 구성에 대해 같은 다운스트림 출력을 생성합니다.

어노테이션 네임스페이스 분리:

접두사소유자목적
aggrega.ai/Aggrega 플랫폼 전용프로바이더가 직접 읽는 플랫폼 네이티브 어노테이션(예: aggrega.ai/namespace).
feature.aggrega.ai/공식 표준 라이브러리Manifest에서 바인딩되는 Feature 어노테이션 단축 표기.
{any-other-domain}/엔터프라이즈 / 커뮤니티사용자 정의 Feature 어노테이션 단축 표기.

aggrega.ai/ 접두사 예약

Manifest의 features.annotations 바인딩은 단독 aggrega.ai/ 접두사를 사용할 수 없습니다. 이 접두사는 컴파일러가 내보내는 플랫폼 네이티브 어노테이션(OTel/provenance 레이블 등)용으로 예약되어 있습니다. 범위가 지정된 하위 접두사(component.aggrega.ai/*, compliance.aggrega.ai/*, 엔터프라이즈용 acme.aggrega.ai/*)는 사용자 작성에 계속 사용할 수 있습니다. 플랫폼에 예약된 어노테이션 집합은 providers/well-known-annotations를 참조하십시오.