Component
Component 엔터티의 개념적 역할(Domain 2의 추상 컴퓨트 노드 인터페이스)은 architecture/04-entity-taxonomy.md에서 다룹니다. 이 페이지는 Component 작성 영역을 다룹니다. 아키텍트가 운영 기반 온톨로지 위에 인지적 정체성을 덧입히는 데 사용하는 Semantic Label Taxonomy, 데이터 축을 위한 schema: 선언, 토폴로지 소켓과 부착 슬롯을 위한 usesSchema 및 featuresSchema 선언형 테이블, 존재 의무, extends: 상속 메커니즘, 그리고 필드 간 규칙 블록인 assertions:가 여기에 해당합니다.
시맨틱 레이블 분류 체계(표준 라이브러리 관례)
기본 타입이 순수하게 클라우드 네이티브라면, 아키텍처의 운영적·인지적 지능은 전적으로 시맨틱 덕 타이핑을 통해 계층화됩니다.
핵심 Go 컴파일러는 이 레이블을 해석하지 않습니다. 컴파일러는 레이블의 의미를 해석하지 않고 평탄한 중간 표현(IR) 그래프를 구성합니다. 이 레이블은 표준 라이브러리 관례, 즉 Domain 2에서 플랫폼 아키텍트가 작성하는 불변의 “유전 표지”를 나타냅니다. 이 레이블은 Wasm 정책 검증기와 물리적 Ops Recipes가 아키텍처를 관리하는 데 사용하는 명시적인 시맨틱 훅을 제공합니다.
(A) 범용 클라우드 계층 이 레이블은 보편적인 동작을 기술하여, 정책 엔진과 생성된 L7 프록시가 AI 프레임워크를 네이티브로 이해하지 않고도 표준 엔터프라이즈 아키텍처를 관리할 수 있게 합니다.
| 레이블 접두사 | 허용 값(관례) | Platform Ops에 필요한 이유(정책 훅) |
|---|---|---|
tool.aggrega.ai/impact | read-only, mutating | 정책 엔진이 최소 권한 AuthZ를 평가할 수 있게 합니다. 변경을 수행하는 도구는 엄격한 승인 게이트 사이드카의 부착을 요구하는 정책을 자동으로 트리거할 수 있습니다. |
datastore.aggrega.ai/engine | relational, document, kv, vector, graph, semantic-memory, search(채워진 카탈로그에 맞춰 안정화 중인 값 집합) | 정책 엔진이 노드 간 타입 안전성을 강제할 수 있게 합니다(예: 에이전트가 Vector DB에 SQL 페이로드를 보내려는 시도를 방지). |
gateway.aggrega.ai/intelligence | semantic, l4-mesh | 라우터가 물리적으로 지원할 수 있는 기능을 결정합니다(예: 폴백 체인처럼 요청이 지정하는 모델을 기준으로 라우팅하는 Feature가 표준 TCP 메시에 부착되는 것을 방지). |
dataplane.aggrega.ai/request-mirroring | full-rate, sampled | 라이브 트래픽을 두 번째 목적지로 복사하는 Feature가 복사 자체가 가능한 프록시를 선택하고, 일치하는 모든 요청을 복사하는 프록시와 복사할 요청의 비율을 설정할 수 있는 프록시를 구별할 수 있게 합니다. |
dataplane.aggrega.ai/caller-identity | client-certificate, injected-header | 프록시 뒤의 서비스에 원래 호출자를 식별해 주어야 하는 Feature가 그 신원을 전달할 수 있는 구성 요소를 선택하고, 어떤 메커니즘이 이를 전달하는지, 즉 클라이언트 자신의 TLS 인증서 정보를 그대로 전달하는지, 아니면 호출자를 인증한 뒤 프록시가 직접 구성한 헤더로 전달하는지를 읽을 수 있게 합니다. |
dataplane.aggrega.ai/content-masking | entity-recognition, pattern-list | 민감한 텍스트를 마스킹하는 Feature가, 라우팅하는 채팅 및 완성 페이로드에서 텍스트가 더 전달되기 전에 이를 자리 표시자로 대체할 수 있는 구성 요소를 선택할 수 있게 합니다. 값은 충실도를 나타냅니다. entity-recognition이면 구성 요소는 자체 구성에 제공된 패턴과 일치하는 부분, 그리고 호출하는 인식기 서비스가 탐지한 엔터티 유형도 대체합니다. pattern-list이면 자체 구성에 제공된 패턴과 일치하는 부분만 대체하며 인식기 서비스를 호출하지 않습니다. |
dataplane.aggrega.ai/prompt-guard | pattern-list, classifier | 모델 프롬프트를 검사하는 Feature가, 라우팅하는 채팅 및 완성 페이로드를 검사하고 그 내용에 따라 요청을 거부할 수 있는 구성 요소를 선택할 수 있게 합니다. 값은 충실도를 나타냅니다. pattern-list이면 임의의 HTTP 본문이 아닌 모델 페이로드를 대상으로, 자체 구성에 제공된 패턴과 대조합니다. classifier이면 판정은 구성 요소가 호출하는 탐지 서비스를 통해 얻은, 학습된 텍스트 분류기의 판정이며 자체 구성에 제공된 임곗값을 기준으로 합니다. |
dataplane.aggrega.ai/upstream-tls | trust-anchor | 프록시가 통신 상대를 확인해야 하는 Feature가, Release가 제공하는 신뢰 앵커로 업스트림의 인증서를 검증할 수 있는 구성 요소를 선택할 수 있게 합니다. |
dataplane.aggrega.ai/upstream-pinning | public-key | 업스트림이 제시할 수 있는 키를 고정하는 Feature가, 업스트림이 제시한 인증서가 Release가 제공하는 공개 키 중 하나를 담고 있지 않으면 해당 업스트림을 거부할 수 있는 구성 요소를 선택할 수 있게 합니다. upstream-tls와는 다른 주장입니다. 핀은 인증서가 어떤 키여야 하는지를, 앵커는 인증서가 무엇을 명시해야 하는지를 말합니다. |
dataplane.aggrega.ai/period-budget | cost, tokens | 일정 기간 동안 트래픽이 소비할 수 있는 양을 제한하는 Feature가, 해당 기간 동안 집계한 양이 자체 구성에 설정된 한도를 넘으면 모델 요청을 거부할 수 있는 구성 요소를 선택할 수 있게 합니다. 값은 무엇을 집계하는지를 나타냅니다. cost는 트래픽에 든 비용으로, 구성 요소가 모델별로 보관하는 표에서 가격을 매깁니다. tokens는 각 모델의 응답이 읽기, 쓰기 또는 둘 다로 보고하는 토큰으로, 구성 요소는 이를 집계만 하고 가격을 매기지 않습니다. |
dataplane.aggrega.ai/concurrency-cap | total, per-target | 구성 요소가 동시에 처리하는 요청 수를 제한하는 Feature가, 자체 구성에 설정된 상한을 넘는 요청을 보류하거나 거부할 수 있는 구성 요소를 선택할 수 있게 합니다. 값은 하나의 상한이 무엇을 세는지를 나타냅니다. total은 구성 요소가 전달하는 모든 요청을 하나의 상한으로 셉니다. per-target은 요청을 보내는 각 업스트림 대상으로 진행 중인 요청을 대상별 상한으로 세며, 그 합계에는 상한이 없습니다. |
dataplane.aggrega.ai/ 키는 구성 요소의 종류가 아니라 트래픽 경로상의 위치를 나타내므로,
프록시, 인그레스 게이트웨이, 서비스 메시가 각자의 어휘를 따로 둘 필요 없이
하나의 어휘로 자신을 기술합니다. 이 계열의 두 가지 속성은 뒤바꿔 이해하기 쉬우므로
주의 깊게 읽을 필요가 있습니다.
- 값은 기능의 존재만이 아니라 충실도를 담습니다. 두 구성 요소가 모두 요청을 미러링할 수 있으면서도 Feature가 신경 쓰는 방식에서 다를 수 있으므로, 그 구별은 값에 담기고 Feature는 필요한 충실도를 선택합니다. 더 강한 충실도를 제공하는 구성 요소는 더 강한 값만 가지며 다른 값은 가지지 않습니다.
- 값은 제품이 할 수 있는 일을 주장하며, 배포가 무엇을
켰는지는 결코 주장하지 않습니다. 두 가지는 비슷하게 읽히지만 앞의 것만이
구성 요소의 속성입니다. 업스트림 인증서를 검증할 수 있는 프록시는 특정 배포가
그 검사를 활성화하는지와 관계없이
upstream-tls: trust-anchor를 가집니다. 레이블은 무엇이든 구성되기 전에 Feature가 선택 기준으로 삼는 것이기 때문입니다.
이러한 축 중 하나에서 기술할 것이 없는 구성 요소는 가장 약한 값을 두는 대신 그 축에 값을 두지 않습니다. 분류 체계의 다른 곳과 똑같습니다. 값이 없다는 것은 그 구성 요소에서 해당 축이 다룰 대상이 없다는 뜻이므로, 그 축에 어떤 값이든 요구하는 Feature는 올바르게 부착되지 않습니다.
(B) 특화된 AI 계층(인지적 정체성) 이 레이블은 워크로드의 인지적 정체성을 기술하여, 아키텍처가 최신 AI 프레임워크를 보호할 수 있게 합니다.
| 레이블 접두사 | 허용 값(관례) | Platform Ops에 필요한 이유(정책 훅) |
|---|---|---|
model.aggrega.ai/capability | generative, embedding, transcription | usesSchema 셀렉터 문자열(정적 분석 중 Go 컴파일러가 네이티브로 평가)에서 사용되어, 개발자가 실수로 생성형 텍스트 페이로드를 임베딩 엔드포인트로 라우팅하지 않도록 보장합니다. |
model.aggrega.ai/api | openai, anthropic, gemini, native | 구성 요소가 게시하는 주소에서 어떤 모델 API가 응답하는지를 나타냅니다. OpenAI API(벤더 자체 구현이든 서버의 구현이든)이면 openai, Anthropic의 Messages API(벤더 자체 구현이든 서버의 구현이든)이면 anthropic, Google의 Gemini API이면 gemini, 그중 어느 것도 아닌 제품 자체 API이면 native입니다. 모든 모델 구성 요소가 이를 가지며, 모델 API를 제공할 수 있는 게이트웨이도 마찬가지입니다. 따라서 component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api를 선택하는 소켓은 모델 또는 그러한 게이트웨이를 받아들이고 아무것도 제공할 수 없는 게이트웨이는 거부하며, model.aggrega.ai/api=anthropic처럼 하나의 값을 지정하는 소켓은 해당 API를 제공하는 것만 받아들입니다. 이 레이블은 하나의 Release가 무엇을 연결하는지가 아니라 제품이 무엇을 제공하는지를 나타냅니다. 모델이 자체 소켓에 연결되는 게이트웨이는 아무것도 연결되지 않았어도 이 레이블을 가집니다. 이 레이블은 셀렉터가 일치시키는 문자열일 뿐이며, 해당 주소에서 실제로 무엇이 응답하는지는 아무것도 확인하지 않습니다. |
agent.aggrega.ai/autonomy | autonomous, copilot | 인지 루프의 실행 위험을 식별하여, 정책이 완전 자율 에이전트에 사람 승인 기능을 의무화할 수 있게 합니다. |
(C) 교차 관심사(거버넌스, 상태 및 하드웨어) 이는 제로 트러스트 검증과 하드웨어 라우팅을 이끄는 기본 엔터프라이즈 태그를 나타냅니다.
| 레이블 접두사 | 허용 값(관례) | Platform Ops에 필요한 이유(정책 훅) |
|---|---|---|
component.aggrega.ai/hosting | self-hosted, managed, external, mixed | 구성 요소의 기반 리소스를 누가 운영하는지, 즉 신뢰 경계 축을 기록합니다. 정책 엔진은 이를 읽어 데이터 유출 위험을 계산합니다(예: managed 서드파티 API로 라우팅된 내부 데이터는 운영자의 경계를 벗어남). 교차 관심사: 같은 값이 관리형 데이터베이스, 관리형 모델 API, 직접 운영하는 추론 서버를 똑같이 기술합니다. mixed는 Recipes가 둘 이상의 운영 방식에 걸쳐 있는 component를 표시합니다. 예를 들어 Helm 및 Compose Recipes로는 자체 호스팅되고 RDS Recipes로는 관리형으로 운영되는 데이터 저장소입니다. 따라서 Release의 운영 방식은 그 Manifest가 선택하는 Recipe를 따릅니다. |
compliance.aggrega.ai/data-class | public, internal, restricted | Component가 보유하는 데이터의 등급입니다. 컴파일러는 이를 문자열로 빌드 그래프에 전달할 뿐 순위를 매기지 않습니다. 운영자가 ir-verdict 역할에 연결하는 정책이 자체 설정에서 등급의 순서를 정하고, 컴파일러가 열거하는 경로를 따라 레이블을 읽습니다. 예를 들어 restricted component가 경로상에 등급 해제 Feature가 연결되지 않은 채 다른 등급의 component에 도달하는 빌드를 중단합니다(policy-data-class-route). 표준 라이브러리의 어떤 Component도 이 레이블을 갖지 않습니다. 등급은 조직이 component를 어떻게 사용하는지에 대한 진술이므로, 조직 자체의 Component가 이를 가집니다. 예를 들면 extends를 통한 특수화입니다. |
compliance.aggrega.ai/contains-pii | true, false | GDPR/CCPA 적용 범위의 워크로드를 명시적으로 표시합니다. 운영자가 연결하는 정책은 이를 읽어 해당 워크로드의 트래픽이 지나는 경로에 특정 Features를 요구할 수 있습니다. 예를 들어 워크로드가 모델 트래픽을 보내는 AI 게이트웨이에 core/data-masking을 요구하는 것으로, policy-data-class-route가 데이터 등급에 대해 검사하는 형태입니다. 표준 라이브러리의 어떤 Component도 이 레이블을 갖지 않습니다. 데이터 등급과 마찬가지로, 이는 조직이 자체 component에 대해 내리는 진술입니다. |
hardware.aggrega.ai/accelerator | gpu, tpu, npu | DevOps가 Release 파일에서 사용합니다. components: {} 맵을 통해 이러한 component를 물리적 하드웨어 풀 경계(예: GPU 지원 클러스터)로 명시적으로 라우팅하며, 거버넌스 판정 역할은 GPU 레이블이 붙은 component가 GPU가 없는 경계에 절대 배치되지 않도록 강제할 수 있습니다. |
state.aggrega.ai/retention | retain, delete | AOT 삭제 공백을 해결합니다. 개발자가 Aggregate에서 데이터베이스를 삭제하면 GitOps 오케스트레이터는 디스크를 물리적으로 삭제합니다. Recipe의 pipeline: 단계는 retain 레이블을 읽고 렌더링된 아티팩트에 오케스트레이터 고유의 보호 장치(예: helm.sh/resource-policy: keep)를 추가할 수 있습니다. |
state.aggrega.ai/backup-tier | mission-critical, standard, ephemeral | SOC2 가용성 훅. Ops FeatureRecipe에 해당 리소스에 대한 자동 스냅샷/볼륨 백업 구성을 물리적으로 생성할지 여부를 알려 줍니다. |
(D) 동적 비즈니스 컨텍스트(계단식 어노테이션) labels가 변경 불가능한 카탈로그 DNA를 정의하는 반면, 동적 비즈니스 컨텍스트(SOC2 감사 범위 지정이나 FinOps 비용 추적 등)는 애플리케이션을 누가 배포하고 어디에서 실행하는지에 따라 달라집니다. 이는 개발자의 subsystems, Ops Release 경계, 또는 annotation-transform 역할로 연결된 거버넌스 플러그인이 동적으로 주입하는 어노테이션으로 관리됩니다.
| 어노테이션 접두사 | 허용 값(관례) | Platform Ops에 필요한 이유(정책 훅) |
|---|---|---|
business.aggrega.ai/cost-center | 예: finance, ai-research | 클라우드 과금 대시보드를 위해 최종 생성 아티팩트에 물리적 태그(예: AWS 태그 또는 K8s 레이블)를 주입하려면 Wasm 렌더링 플러그인에 필요합니다. |
business.aggrega.ai/owner | 예: team-alpha@corp.com | 인시던트 대응 라우팅. 인프라가 담당 팀에 매핑되도록 보장합니다. |
compliance.aggrega.ai/frameworks | 예: soc2, hipaa | SOC2 범위 트리거. 환경 Release를 통해 주입됩니다. Wasm 플러그인은 이 문자열을 읽어, 애플리케이션이 프로덕션 컴플라이언스 경계에 들어갈 때 엄격한 감사 로깅 사이드카를 자동으로 생성하고 디버그 포트를 비활성화합니다. |
이 분류 체계는 컴파일러 규칙이 아니라 카탈로그 관례입니다. 기업은 이를 무시하거나 삭제하거나 자체 레이블 어휘(mycompany.com/custom-trait)를 만들 수 있습니다. Wasm 플러그인은 기업이 작성하는 어떤 레이블 키든 평가합니다.
스키마 작성
Component 스키마(및 feature.aggrega.ai/kind: secret 레이블이 붙은 자격 증명 Features를 포함한 그 짝인 Feature)는 spec.schema: 블록을 통해 개발자가 작성한 values에 대한 검증 계약을 선언합니다. 이 블록은 JSON Schema 2020-12를 간결한 형식의 YAML 축약 표기(기본값이며, 약 15개의 키워드로 구성되고 컴파일 시점에 기계적으로 JSON Schema로 변환됨) 또는 완전한 JSON Schema YAML(장황한 형식)로 표현한 것을 받으며, 여러 Components가 공유하는 SchemaLibrary 항목에 대해서는 $ref:를 통한 문서 간 참조를 사용합니다.
- 인라인 간결한 형식(기본 작성 방식): 간결한 형식의 리프를 Component YAML 안에 직접 담는 내장 YAML 블록입니다. 카탈로그 스키마 내용의 대부분을 완전한 JSON Schema 줄 수의 일부만으로 표현할 수 있습니다. 키워드 어휘와 작성 관례는
vocabulary/compact-form-authoring.md를 참조하십시오. - 인라인 JSON Schema YAML: 장황한 형식으로, 간결한 형식이 직접 지원하지 않는 JSON Schema 2020-12 키워드(
$dynamicRef, 깊은unevaluatedProperties, 복잡한not:조합)가 스키마에 필요할 때 적합합니다. 간결한 형식과 JSON Schema는$jsonschema:탈출구를 통해 단일schema:블록 안의 어느 노드 경계에서든 혼용할 수 있습니다. - 문서 간 참조(SchemaLibrary 항목에 대한
$ref:): SchemaLibrary 항목을 식별자(Datastores#/schemas/MariaDBValues또는 유사한 형태)로 가리키는 JSON Schema 고유의$ref:입니다. 수백 줄에 걸치고 여러 Components에서 재사용되는 엔터프라이즈 스키마는 SchemaLibrary 엔터티에 두며, 이를 소비하는 Component는 내용을 인라인하지 않고 해당 항목을 참조합니다. 라이브러리 엔터티와 해석 의미론은entities/schemalibrary.md와vocabulary/cross-document-ref.md를 참조하십시오.
위의 세 가지 형식은 필라 내용을 작성하는 방식이며, 아무것도 확장하지 않는 Component에서 사용할 수 있습니다. extends:를 선언한 Component는 필라 내용을 전혀 작성하지 않습니다. 이 Component는 리터럴 마커 schema: inherited를 작성하고, 베이스가 작성한 그대로의 필라 블록을 받습니다. 이러한 Component에서 schema:가 가질 수 있는 값은 이 마커뿐입니다. 아래의 “카탈로그 작성: 베이스 Components 확장”을 참조하십시오.
컴파일러는 Component의 검증 단계에서 schema: 블록을 해석하고(간결한 형식을 확장하고, $ref: URL을 역참조하고, SchemaLibrary의 라이브러리 간 체인을 적용함), 그 결과로 얻은 JSON Schema를 usesSchema와 featuresSchema에서 파생된 자동 생성 베이스(아래 절 참조)와 통합합니다. 검증은 해석된 스키마를 대상으로 실행되며, 작성 경로는 하위 파이프라인 단계에 드러나지 않습니다.
작성된 인스턴스는 빌드 시점에 이 해석된 스키마를 기준으로 검증됩니다. 컴포넌트 인스턴스의 개발자가 작성한 values와 Operator가 해석한 infra, 그리고 모든 Feature 연결의 values/infra는 선언된 필라를 준수해야 합니다. 잘못된 타입의 값, 범위를 벗어난 숫자, 선언된 format을 갖지 않는 문자열, 누락된 필수 필드, 또는 (닫힌 방식으로 검증되는 values의 경우) 선언되지 않은 속성은 배포 시점에 깨진 매니페스트를 만드는 대신 작성된 소스 위치에서 빌드를 중단시킵니다. 컴파일러가 검사하지 않는 format을 스키마에서 지정한 필라는 카탈로그를 로드할 때 거부되며, 지원되는 이름 목록이 함께 표시됩니다. email, uri, hostname, ipv4, ipv6, uuid, date-time, date 이외의 모든 것이 해당하며 password도 포함됩니다. 각 이름이 무엇을 검사하는지는 vocabulary/compact-form-authoring.md를 참조하십시오. 베이스를 extends:하는 Component의 인스턴스는 확장하는 Component가 변경 없이 상속하는 베이스의 필라 블록을 기준으로 검증됩니다. 따라서 베이스의 인스턴스와 이를 확장하는 모든 것의 인스턴스는 동일한 필라 계약을 따릅니다. 진단 메시지와 필라별 규칙(infra가 Component와 provider 키의 합집합을 기준으로 검증되는 방식 포함)은 errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema(작성된 values 또는 infra가 선언된 스키마를 준수하지 않음)”를 참조하십시오.
선언된 기본값은 렌더링된 필라에 구체화됩니다. 검증 외에도, values 필드(또는 infra 필드)에 선언된 default:는 작성자가 생략한 모든 키에 대해 빌드 시점에 렌더링된 필라에 채워집니다. 따라서 {{ .values.charset }}를 읽는 Recipe 템플릿은 빈 값 대신 스키마에 선언된 utf8mb4를 받습니다. 작성자가 제공한 값이 항상 우선하며, 중첩 객체는 생략된 자식별로 채워집니다. 구체화는 검증과 동일한 스키마 해석을 사용하므로, SchemaLibrary로의 문서 간 $ref:를 통해 도달한 기본값도 구체화됩니다. 필라 전체 참조(values: {$ref: "BaseComponents#/schemas/BaseModelParameter"})와 베이스-플러스-플레이버 형태(형제 properties와 함께 쓰인 베이스 $ref:로, 각각 자체 기본값을 가짐) 모두 해당합니다. 로컬 문서 내 #/$defs/ 참조 안에서만 선언되었거나 allOf / oneOf / anyOf 분기 아래에 선언된 기본값은 구체화되지 않습니다. 표준 라이브러리는 구체화되는 방식인 문서 간 $ref:를 통해 필라를 구성합니다.
values 필러
Component 스키마는 소유권에 따라 세 가지 필러를 분리합니다. values는 Aggregate에서 Developer가 채우고(인지적 의도 — 데이터베이스 이름, 버전, 문자 집합), infra는 Release에서 Operator가 채우며(운영 규모 — 컴퓨팅, 스토리지, HA), provides는 Recipe가 설정합니다(공개 API 계약 — 호스트, 포트, 프로토콜). Developer는 infra를 보지 않으며, Operator는 values를 보지 않습니다. Recipes는 기본 렌더링 중에 두 필러를 모두 소비하여, 추상적인 필러를 대상 provider가 기대하는 구체적인 형태로 매핑합니다. 이 섹션에서는 values 필러의 작성 표면을 다룹니다. 더 넓은 필러 분류 체계와 필러 간 캐스케이드 원칙은 vocabulary/data-pillars.md를 참조하십시오.
values는 Developer의 인지적 의도, 즉 애플리케이션의 규모나 실행 방식이 아니라 애플리케이션이 무엇이고 무엇을 하는지를 설명하는 선택을 담습니다. 데이터베이스 이름, 문자 집합, 엔진 버전, 로그 수준, 기능 플래그, 그리고 애플리케이션 버전 간에는 바뀌지만 환경 간에는 안정적으로 유지되는 애플리케이션 계층 설정이 전형적인 values 내용입니다. Operator는 values:를 재정의하지 않습니다(architecture/06-data-taxonomy-and-composition.md §8 제약 4에 따라 Release 스키마가 values: 블록을 기계적으로 거부합니다). 환경별 차이는 Parameter Hoisting을 통해 전달됩니다. Aggregate가 타입이 지정된 parameters.*를 노출하고, Component의 values 템플릿이 이를 참조하며, Release가 파라미터를 채웁니다.
# Component schema declares the values shape:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] } engine_version: { type: string, default: "10.11" } log_level: { type: string, default: info, enum: [debug, info, warn, error] }# Aggregate fragment — the developer fills values:components: customer-db: type: core/datastore/mariadb values: database_name: customers charset: utf8mb4 engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting log_level: infoRecipe 측 소비. Recipes는 valuesMapping:, provides:, assertions: 및 기타 템플릿 표면에서 .values.<field>를 통해 해석된 값을 읽습니다. 템플릿별 사용 가능 여부 매트릭스는 entities/recipe.md를 참조하십시오. 컴파일러는 해석된 템플릿 컨텍스트가 적용 가능한 모든 필드를 담도록, 같은 Component 노드에서 Component의 values 스키마를 모든 Feature 첨부의 values: 스키마와 통합합니다.
필러 간 원칙. values는 Developer가 Aggregate에서 작성하는 유일한 필러입니다. 엄격히 개발자 대상인 필드는 여기에 속합니다. 운영 설정(레플리카 수, CPU/메모리 한도)은 Release에 위치하도록 Component의 infra 필러에 속하며, 공개 출력(호스트, 포트)은 Recipe의 provides에 속합니다. 이들을 섞으면 소유권 불변식이 깨집니다. 의도적인 필러 간 연결이 정당화되는 드문 경우는 vocabulary/data-pillars.md의 “Cross-pillar mechanics”를 참조하십시오.
infra 축
Component 스키마는 소유권에 따라 세 개의 축을 구분합니다. values는 Developer가 Aggregate에서 채우고(인지적 의도 — 데이터베이스 이름, 버전, 문자 집합), infra는 Operator가 Release에서 채우며(운영 규모 — 컴퓨팅, 스토리지, HA. 데이터 저장소의 백업은 여기서 규모를 정하지 않고, Operator가 Release에서 연결하는 core/backup Feature가 담당합니다), provides는 Recipe가 설정합니다(공개 API 계약 — 호스트, 포트, 프로토콜). Developer는 infra를 보지 않으며, Operator는 values를 보지 않습니다. Recipes는 기본 렌더링 중에 두 축을 모두 소비하여, 추상적인 축을 대상 provider가 기대하는 구체적인 형태로 매핑합니다.
표준 라이브러리에서 기능에 구애받지 않는 모든 Component에 걸쳐 중요한 infra 관례는 세 가지입니다. provider별 설정 항목을 위한 열린 구조체 탈출구, 업스트림 아티팩트 버전에 대한 선택적 재정의, 그리고 고가용성 필드를 위한 의도 기반 어휘입니다. 표준 참조 Component는 표준 라이브러리 카탈로그의 core/datastore/mariadb입니다. 이 Component는 공식 mariadb 이미지를 실행하거나 MariaDB 사용자 정의 리소스를 mariadb-operator 컨트롤러에 넘기는 Helm Recipes, AWS RDS를 대상으로 하는 Terraform Recipes, 같은 RDS 표면을 대상으로 하는 CloudFormation Recipes, 로컬 컨테이너를 대상으로 하는 Compose Recipes로 구현할 수 있으며, 그 infra 블록은 첫 번째와 세 번째 패턴을 보여 줍니다.
infra.overrides
범용 infra 필드인 compute, storage, ha는 provider 전반에 걸친 운영 규모 대부분을 다룹니다. 나머지 부분은 본질적으로 provider에 특화되어 있습니다. Kubernetes Recipe에는 nodeSelector가, RDS Terraform Recipe에는 instance_class가, CloudFormation RDS Recipe에는 DBInstanceClass가, Compose Recipe에는 image 재정의가 필요합니다. Component 스키마는 이러한 설정 항목이 스키마를 비대하게 만들지 않고 전달되도록 진정으로 열린 맵을 탈출구로 노출합니다.
infra: # ... universal fields ...
# Provider-specific overrides. Accepts any nested structure. # Each Recipe documents which keys it reads. overrides: type: object additionalProperties: true # genuinely open map: arbitrary nested structure permittedadditionalProperties: true와 함께 명시한 type: object는 열린 맵 의미 체계를 선택합니다. 컴파일러는 이 구조를 손대지 않고 그대로 전달하며, Recipe의 템플릿 본문은 자신이 아는 키만 읽고 나머지는 무시합니다. 각 Recipe는 헤더 주석에 재정의 키 체계를 문서화하므로, 특정 Component × Recipe 조합에 대한 Release를 작성하는 Operator는 해당 Recipe가 어떤 설정 항목을 노출하는지 알 수 있습니다.
overrides를 사용하는 Release 조각:
components: main-db: infra: compute: { cpu: "2", memory: 8Gi } storage: { size: 40Gi, type: balanced-csi } overrides: nodeSelector: kubernetes.io/hostname: cluster1-worker1 service_type: LoadBalancer metrics: enabled: true image: repository: bitnamilegacy/mysqld-exporterDeveloper는 overrides를 보지 않습니다. 이는 Operator의 영역인 Release에 존재합니다.
infra.source_version
Recipe의 source 필드는 특정 버전의 업스트림 아티팩트(Helm 차트 25.0.8, Terraform 모듈 4.2.0, OCI 이미지 태그)를 참조합니다. Recipe 안에 버전을 하드코딩하면 카탈로그 관리자는 호환되는 업스트림 버전이 올라갈 때마다 새 Recipe를 게시해야 합니다. Component 스키마는 선택적 재정의를 노출합니다.
infra: source_version: type: string description: | Source artifact version. A Recipe versions its artifact from this key where its source resolution reads it, and is unaffected where it does not. Changing from the version a Recipe was authored against does not guarantee value mapping compatibility.Recipe는 source 블록에서 optional 헬퍼를 통해 이 값을 읽으므로,
고정 값이 없으면 Recipe가 작성될 때 기준으로 삼은 버전으로 대체됩니다.
source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` `25.0.8` }}"Recipe source 문자열(및 구조화된 source: 맵의 문자열 값 하위 필드)은 Go 템플릿으로 평가됩니다. 위의 version과 같은 원격 좌표는 aggrega pull이 아티팩트를 고정할 때 .context 루트 없이 .values, .infra, .locals를 대상으로 평가되고, 워크스페이스 안의 경로를 지정하는 source는 엔터티가 렌더링될 때 Recipe locals와 동일한 자기 완결적 컨텍스트, 즉 .context.instance_id, .values, .infra, 노드의 해석된 .locals 전체를 대상으로 평가됩니다. 두 경우 모두 .context.inject, .context.uses, .provides는 금지됩니다. 이 컨텍스트에 .infra가 있기 때문에 위의 재정의가 동작하며, .locals를 통해 Recipe는 source 조각을 한 번 계산하고 여기서 다시 읽을 수 있습니다. source 템플릿은 자기 노드의 provides를 절대 읽지 않습니다. 그 축은 컨텍스트에 포함되지 않으며, 이를 참조하려는 템플릿은 빌드를 중단시킵니다. 이는 이후 작업을 기다리는 공백이 아니라 이 표면의 고정된 속성입니다. 전체 사용 가능 규칙은 템플릿 확장 매트릭스 5번 행을 참조하십시오. infra.source_version을 Recipe의 기본값과 다르게 변경한다고 해서 Recipe의 valuesMapping이 새 업스트림 버전과 호환된다고 보장되지는 않습니다. 이 경고는 Component 스키마의 source_version 선언에 있는 description에 담겨 있습니다.
infra.ha.*
고가용성 필드는 메커니즘 어휘가 아닌 의도 어휘를 사용합니다.
infra: ha: enabled: { type: boolean, default: false } read_replicas: { type: integer, min: 0, default: 0 }infra.ha.enabled는 “이 Component를 고가용성으로 만들라”는 뜻이고, infra.ha.read_replicas는 “읽기 전용 사본 N개를 원한다”는 뜻입니다. 그 의도가 자신의 provider에서 무엇이 되는지는 각 Recipe가 결정합니다. core/datastore/mariadb의 표준 라이브러리 Recipes를 Manifest가 매핑할 때의 이름으로 나열하면 다음과 같습니다.
| Recipe | ha.enabled: true의 매핑 대상 | ha.read_replicas: N의 매핑 대상 |
|---|---|---|
helm/mariadb(공식 mariadb 이미지 기반 StatefulSet) | 서버를 하나만 실행하므로 키를 지목하며 빌드가 중단됨 | 서버를 하나만 실행하므로 N이 0보다 크면 빌드가 중단됨 |
helm/mariadb-cluster(mariadb-operator 컨트롤러가 조정하는 MariaDB 사용자 정의 리소스) | 자동 장애 조치를 켬(replication.primary.autoFailover: true). 읽기 복제본으로 장애 조치하므로 N이 0이면 빌드가 중단됨 | spec.replicas를 N + 1로 설정하고 복제를 켬. provides.host는 <name>-primary Service가 됨 |
terraform/mariadb-rds(AWS RDS) | 기본 aws_db_instance에 multi_az = true 설정 | 별도의 aws_db_instance 읽기 복제본 리소스 N개 생성 |
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules(모듈을 통한 AWS RDS) | multi_az = true를 모듈에 전달함 | 인스턴스를 하나만 프로비저닝하므로 N이 0보다 크면 빌드가 중단됨 |
cloudformation/mariadb-rds(AWS RDS) | AWS::RDS::DBInstance에 MultiAZ: true 설정 | 인스턴스를 하나만 프로비저닝하므로 N이 0보다 크면 빌드가 중단됨 |
compose/mariadb(로컬 개발 컨테이너) | 서버를 하나만 실행하므로 키를 지목하며 빌드가 중단됨 | 서버를 하나만 실행하므로 N이 0보다 크면 빌드가 중단됨 |
메커니즘 어휘(infra.primary.replicas)는 한 provider에서는 자연스럽게 읽히지만(Kubernetes 파드는 StatefulSet의 복제본입니다) 다른 곳에서는 범주 오류가 됩니다. RDS에는 기본 인스턴스에 “복제본” 개념이 없고, CloudFormation은 RDS를 그대로 따르며, Compose에는 수평 복제본 추상화가 전혀 없습니다. 의도 어휘는 번역이 가능합니다. 모든 provider에는 “이 데이터베이스를 고가용성으로 만들라”는 개념과 “읽기 전용 사본 N개를 원한다”는 개념이 어떤 형태로든 있으며, provider별 번역은 Recipe가 담당합니다. 구현에 그러한 메커니즘이 없으면 그 Recipe는 키를 지목하며 빌드를 중단할 수 있습니다. helm/mariadb와 compose/mariadb는 두 키 모두에 대해, 단일 인스턴스 RDS Recipes는 읽기 복제본에 대해 그렇게 합니다.
infra.ha.read_replicas: 0이 기본값입니다. 두 키가 모두 기본값이면 helm/mariadb-cluster는 인스턴스 하나에 대한 복제가 아니라 replication 블록이 없는 단일 인스턴스 MariaDB를 렌더링합니다. compose/mariadb는 로컬 Docker 호스트에서 서버를 하나만 실행하므로, infra.ha.enabled: true 또는 0이 아닌 infra.ha.read_replicas는 키를 지목하며 빌드를 중단시키고, 메시지는 장애 조치와 읽기 복제본을 제공하는 helm/mariadb-cluster를 안내합니다.
provides 축
provides는 Recipe가 작성하는 공개 API입니다. 즉 Component의 해석된 Recipe가 다운스트림 호출자에게 그들의 .context.uses.<alias>.provides.<provided-name> 표면을 통해(또는 호출자가 엣지에 inject: 허용 목록을 선언한 경우 그 .context.inject 파이프를 통해) 제공하는 값입니다. Component 스키마는 형태(키 이름과 타입)를 선언하고, 바인딩된 Recipe의 provides: 블록이 값을 공급합니다. Aggregate를 작성하는 Developer는 Component 페이지에서 provides 형태를 호출자가 의존할 수 있는 계약으로 보며, Recipe 작성자는 자신이 감싸는 특정 구현에 대해 그 계약을 이행합니다.
이행 여부는 Loud Guardrail로 강제됩니다. 바인딩된 Recipe는 해당 Component가 선언한 모든 provides 키를 생성해야 합니다. 바인딩된 Recipe가 선언된 키를 누락하면, 그 키를 참조하는 호출자에게 아무것도 전달하지 않은 채 조용히 넘어가는 대신 빌드가 중단되고 누락된 키의 이름을 알려 줍니다. 선언된 집합 외에 추가 키를 생성하는 것은 허용됩니다. 검사하는 것은 키의 존재뿐입니다. 생성된 값은 컴파일러가 그대로 전달하는 불투명한 문자열이므로, 선언된 타입은 호출자가 읽는 계약일 뿐 컴파일러가 검증하는 값이 아닙니다.
# Component schema declares the provides contract:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } provides: host: { type: string } port: { type: integer } database: { type: string }# Recipe fulfills the contract:apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" database: "{{ .values.database_name }}" valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"provides 후 inject 평가 분리. 컴파일러는 provides 평가 단계에서 자체 완결된 템플릿 컨텍스트(.context.instance_id, 노드의 provider가 보고하는 경우 .context.rendered_name, .values, .infra, 그리고 같은 노드에서 해석된 Recipe의 locals:)를 대상으로 provides: 템플릿을 평가하며, 호출자 상태는 보이지 않습니다. 노드의 locals는 이 단계의 서두에서 provides보다 먼저 해석되며, 이 덕분에 provides: 템플릿이 .locals를 읽을 수 있습니다. 그다음 실행되는 inject 하이드레이션에서 컴파일러는 uses: 엣지를 순회하며 각 호출자의 .context.uses.<alias>.provides.<provided-name>를 해석된 provides 값에 대해 해석합니다. 둘을 분리하면 비순환 해석이 보장됩니다. provides:는 호출자를 참조할 수 없고, 호출자의 inject:는 inject 하이드레이션이 실행되기 전까지 아직 해석되지 않은 provider의 출력을 참조할 수 없습니다.
계약의 발전. provides 필드의 이름을 바꾸거나 제거하는 것은 이전 이름에 의존하는 모든 호출자에게 호환성을 깨는 변경입니다. Component의 metadata.version(및 Recipe의 implements: 선언)이 계약 발전 신호를 전달하며, 특정 메이저 버전에 고정된 다운스트림 호출자는 안정적인 provides 형태를 보게 됩니다.
Recipe 측 설명. provides: 템플릿 작성 문법, 템플릿별 가용성 매트릭스, 네임스페이스 간 및 리전 간 라우팅의 실제 예시는 entities/recipe.md의 “The provides: block”과 architecture/06-data-taxonomy-and-composition.md §3를 참조하십시오.
존재 의무: features.aggrega.ai/requiredType.<label>
Component는 자신의 모든 인스턴스가 특정 Feature 타입의 어태치먼트를 반드시 가져야 한다고 선언할 수 있습니다. 이것이 존재 의무이며, Component 자체 메타데이터에 반복 가능한 어노테이션으로 작성합니다:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/payment-processor version: 1.0.0 labels: component.aggrega.ai/type: server annotations: features.aggrega.ai/requiredType.audit: core/audit-logging features.aggrega.ai/requiredType.compliance: core/pci-compliancespec: schema: values: processor_endpoint: { type: string, required: true }키는 접두사 features.aggrega.ai/requiredType. 뒤에 직접 정한 레이블을 붙인 것이고, 값은 적어도 하나의 어태치먼트가 가져야 하는 Feature 타입 URI입니다. 레이블은 충족되지 않은 의무가 만들어 내는 진단에서 요구 사항의 이름이 되며(위의 audit와 compliance), 그것이 레이블의 역할 전부입니다. 레이블이 붙은 키를 사용하면 Component가 여러 의무를 한 번에 선언할 수 있습니다. 어노테이션은 평면 문자열 맵이므로 중복 키를 가질 수 없기 때문입니다.
컴파일러는 5-Tier Onion Model 캐스케이드가 모든 스코프를 접은 뒤, 인스턴스의 최종 어태치먼트 집합을 기준으로 각 의무를 평가합니다. 여기에는 Aggregate의 컴포넌트 수준 및 서브시스템 수준 features: 블록, Release의 경계 수준 및 컴포넌트 수준 features: 블록, 그리고 어노테이션 기반 확장으로 생성된 어태치먼트가 포함됩니다. 이 중 어느 것이든 의무를 충족합니다. 이 규칙은 무엇이 존재하는지를 검사할 뿐, 어떻게 그곳에 왔는지는 검사하지 않습니다. 따라서 운영자가 Release에서 모니터링 어노테이션을 설정했기 때문에만 의무가 충족된 Component도, 개발자가 Feature를 직접 연결한 Component와 똑같이 통과합니다.
어떤 어태치먼트도 충족하지 못하는 의무는 컴포넌트 인스턴스, 요구 사항의 레이블, 필요한 타입을 명시하는 진단과 함께 빌드를 중단시킵니다. 어노테이션 값은 불투명한 문자열이므로 컴파일러가 읽기 전에는 그 형태를 검증하는 것이 없습니다. 따라서 Feature 타입 URI가 아닌 값이나 접두사 뒤에 레이블이 없는 키는 선언이 잘못되었다는 별도의 진단과 함께 중단됩니다. 두 진단은 의도적으로 구분됩니다. 잘못된 선언은 카탈로그 엔티티에서 수정하고, 충족되지 않은 요구 사항은 Feature를 연결하여 해결합니다. 그리고 오타가 충족된 요구 사항으로 읽혀서는 결코 안 됩니다.
두 진단 모두 errors/fatal-halts.md의 “Required feature not attached (필수 Feature가 연결되지 않음)”에 설명되어 있습니다.
의무는 슬롯이 아닙니다. 두 표면은 서로 다른 질문에 답하며, 그 차이는 겉모양에 그치지 않습니다:
featuresSchema 슬롯 | 존재 의무 | |
|---|---|---|
| 선언하는 것 | 이름이 있는 바인딩 지점 | 존재해야 하는 것에 대한 제약 |
| 이름으로 역참조 가능 | 예 — from: <slot> 및 .features.<slot>.provides.* | 아니요 — 레이블은 요구 사항의 이름일 뿐입니다 |
| 카디널리티 | 슬롯당 정확히 하나의 채움 | 해당 타입의 어태치먼트 하나 이상 |
| 채움에 대한 제약 | selector, inject, sensitive | 타입 외에는 없음 |
| 자유 어태치먼트로 충족 가능 | 아니요 — 슬롯은 이름으로 채워집니다 | 예 — 어떤 스코프에서든, 어떤 이름으로든 |
| 요구가 충족되지 않을 때 | required: true이고 슬롯 이름에 바인딩되는 것이 없으면 중단 | 해당 타입을 가진 어태치먼트가 없으면 중단 |
두 요구는 동일한 입력, 즉 인스턴스의 최종 어태치먼트 집합을 기준으로 검사되며, 각각 자체 진단과 함께 중단됩니다. 같은 입력에 서로 다른 질문을 하기 때문입니다. 하나는 이름이 있는 바인딩 지점 하나가 바인딩되었는지를, 다른 하나는 어떤 어태치먼트가 명명된 타입을 가지는지를 묻습니다. 어느 쪽도 다른 쪽을 대신하지 않습니다.
Recipe가 연결된 것을 읽어야 할 때는 슬롯을 사용하십시오. Component의 계약이 어떤 기능의 존재를 요구하되 어느 인스턴스가 그것을 제공하는지는 상관하지 않을 때는 의무를 사용하십시오. core/audit-logging을 의무로 지정한 결제 처리 Component는 개발자가 연결을 기억했는지와 관계없이 모든 배포에서 감사 로깅을 갖추게 되고, core/pci-compliance를 의무로 지정한 PCI 준수 Component는 배포 어딘가에 컴플라이언스 Feature가 연결되지 않으면 출시될 수 없습니다.
상속. 기본 Component에 선언된 의무는 그것을 extends:하는 모든 Component에 상속됩니다. 메타데이터 어노테이션은 extends 체인을 따라 병합되며 키마다 자식이 우선하기 때문입니다. 따라서 자식은 같은 레이블을 다른 타입으로 다시 선언하여 상속된 의무의 대상을 바꾸거나, 새 레이블로 자체 의무를 추가할 수 있습니다. 하지만 기본 Component가 선언한 의무를 제거할 수는 없습니다.
토폴로지 소켓: usesSchema
Component는 usesSchema: 블록을 통해 토폴로지 소켓을 선언할 수 있습니다. 이 블록은 featuresSchema와 나란한 선언적 YAML 맵입니다. 각 항목은 Component가 컴포넌트 간 의존성을 받아들이는 소켓의 이름을 정하고, 개발자가 그 소켓에 연결할 수 있는 Component 형태를 규정합니다. 컴파일러는 선언된 소켓에서 JSON Schema 2020-12 검증 규칙을 자동 생성하고, Component 해석 중에 이를 Component의 schema:와 통합합니다. 구조는 usesSchema에서 나오므로 개발자는 schema: 안에 uses: 기둥을 직접 작성하지 않습니다.
# Component declares the sockets it accepts:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/ai-agent/orchestrator version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: primary_datastore: required: true selector: "datastore.aggrega.ai/engine=vector" inject: [env] cache: required: false selector: "datastore.aggrega.ai/engine=kv" inject: [env, file] log_destination: required: false selector: "component.aggrega.ai/category=messaging" inject: []# Aggregate fragment — developer wires the sockets:components: agent: type: core/ai-agent/orchestrator uses: primary_datastore: main: { target: vector-db-instance } log_destination: audit: { target: audit-sink }연결 형식 — 소켓은 하나 또는 여러 대상을 받습니다. 위 예시는 각 소켓을 단일 대상에 연결하지만, 소켓은 여러 대상으로 분기할 수 있습니다. 소켓 값은 다음 두 형식 중 하나로 작성합니다:
uses: # Compact form — a list of target names. Each entry produces an edge # whose alias equals its target. Use it for the single-target case, and # when one socket connects to several peers of the same shape. shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object # carrying its own `target:`, and may carry its own inject directives. # Use when the connections need distinct names or per-edge inject. databases: primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } } replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }별칭은 항상 항목 객체에 매핑되며, 대상 이름만 단독으로 매핑되지 않습니다. databases: { primary: orders-db }는 로드 시 거부되며, target:를 생략한 항목 객체도 마찬가지입니다. 별칭을 따로 지을 필요 없이 단일 대상을 연결하려면 간결한 형식 primary_datastore: [vector-db-instance]를 사용합니다. 이 형식은 대상 이름을 한 번만 쓰고 그로부터 별칭을 도출합니다.
각 항목(리스트 요소 또는 맵 별칭)은 하나의 엣지가 되며 작성 순서대로 유지됩니다. 소켓의 selector:는 그 소켓을 통해 연결된 모든 대상에 적용되며(각 엣지는 정적 분석 중에 독립적으로 타입 검사됩니다), required: true는 최소 하나의 대상이 연결되어야 함을 뜻합니다.
필드 의미:
| 필드 | 타입 | 기본값 | 의미 |
|---|---|---|---|
required | bool | false | true이면 개발자는 이 소켓에 최소 하나의 의존성을 연결해야 합니다. false이면 소켓은 선택 사항입니다. |
selector | string | — | Feature appliesTo가 사용하는 문법으로 된 레이블 셀렉터로, 이 소켓을 통해 연결된 모든 엣지의 대상이 충족해야 합니다. 여기에 적힌 문자열 그대로 읽히며 정적 분석 중에 대상의 레이블에 대해 평가됩니다. 레이블이 이를 충족하지 않는 대상은 빌드를 중단시키며, 문법이 거부하는 셀렉터도 읽지 못한 요구 조건을 명시하며 빌드를 중단시킵니다. 빈 셀렉터는 대상에 아무런 제약도 두지 않습니다. |
inject | string[] | — | 허용되는 inject 전달 메커니즘의 허용 목록입니다(featuresSchema[].inject와 나란함). 없거나 [](빈 목록)이면 블랙박스를 뜻합니다. 즉 개발자의 uses: 항목에 inject: 블록이 허용되지 않으며 Recipe가 전달을 제어합니다. [env, file, arg](비어 있지 않음)이면 투명함을 뜻합니다. 즉 개발자가 의존성의 provides 값을 어떤 메커니즘으로 전달할지 지정할 수 있습니다. 강제됩니다: 아래 “소켓의 inject 허용 목록이 강제되는 곳”을 참조하십시오. |
valueSchema | object | — | 이 소켓을 통해 연결된 엣지에서 개발자가 작성하는 values에 대한 선택적 엣지별 계약입니다(Aggregate에서 작성). schema:와 같은 작성 형식의 JSON Schema 2020-12입니다. 생략하면 소켓은 values 계약을 선언하지 않습니다. |
infraSchema | object | — | 이 소켓을 통해 연결된 엣지에서 운영자가 작성하는 infra에 대한 선택적 엣지별 계약입니다(Release에서 작성). valueSchema와 같은 작성 형식입니다. 생략하면 소켓은 infra 계약을 선언하지 않습니다. |
featuresSchema | map | — | 이 소켓을 통해 연결된 각 연결이 채울 수 있는 첨부 슬롯으로, 슬롯 이름을 키로 하며 각 슬롯은 Component 수준 슬롯이 받는 키를 받습니다. 생략하면 이 소켓을 통한 연결은 첨부를 갖지 않습니다. 아래 “각 연결이 채우는 슬롯”을 참조하십시오. |
소켓의 inject 허용 목록이 강제되는 곳. 허용 목록은 소비자가 전달 형식을 선택할 수 있는지, 있다면 어떤 형식인지에 대한 소켓의 선언입니다. 따라서 엣지와 소켓 선언이 모두 확보되면 그 소켓을 통해 연결된 모든 uses: 엣지에 대해 검사됩니다. 하나의 규칙에서 두 가지 거부가 나오며, 둘 다 빌드를 중단시킵니다:
- 허용 목록에 없는 메커니즘을 지정하는 엣지는 소켓, 위반한 메커니즘, 그리고 소켓이 허용하는 것을 명시하며 중단됩니다. 엣지의 위반 메커니즘은 모두 함께 보고됩니다.
- 허용 목록이 없거나 비어 있는 소켓을 통해 어떤 전달이든 지정하는 엣지도 중단됩니다. 이는 블랙박스 선언이 제 역할을 하는 것입니다. 블랙박스 선언은 “Recipe가 이것을 내부적으로 전달하니 전달 방식을 지정하지 마십시오”라는 뜻이며, 빈 허용 목록은 모든 것을 허용하는 것이 아니라 아무것도 허용하지 않습니다.
소켓은 그것을 선언한 엔티티에서 읽으며, 이는 항상 엣지가 달린 컴포넌트와 같지는 않습니다. Feature 첨부의 uses:에 작성된 엣지는 첨부된 Feature의 usesSchema에 대해 해석되고, 그 밖의 모든 엣지(Aggregate에서 작성되거나, Release에서 연결되거나, 하위 aggregate를 통해 도달한 엣지)는 소비하는 Component의 것에 대해 해석됩니다. extends를 통해 상속된 소켓은 엔티티가 직접 작성한 소켓과 똑같이 읽힙니다.
아무것도 지정하지 않는 엣지는 소켓이 무엇을 선언하든 두 거부의 영향을 받지 않습니다. 소비하는 Recipe에서 .context.uses.<alias>.provides.<name>로 의존성의 값을 읽는 데는 inject: 블록이 필요 없으며 항상 가능합니다. 두 진단은 errors/fatal-halts.md를 참조하십시오.
엣지별 연결 계약 — valueSchema와 infraSchema. 소켓은 어떤 Components가 연결될 수 있는지를 규정하는 것을 넘어, 각 연결이 어떤 구성을 갖는지를 선언할 수 있습니다. 두 가지 선택적 소켓별 스키마가 소켓을 통해 연결된 모든 엣지에서 연결 범위의 구성을 검증합니다:
valueSchema는uses엣지에서 개발자가 작성하는values블록에 대한 계약입니다. 개발자가 Aggregate에서 표현하는 연결별 튜닝(예: 연결 풀 크기나 클라이언트 모드)입니다.infraSchema는uses엣지에서 운영자가 작성하는infra블록에 대한 계약입니다. 운영자가 Release에서 표현하는 연결별 운영 사이징입니다.
둘 다 schema: 필드와 같은 내용 형태 형식(인라인 간결 형식, 인라인 JSON Schema YAML, 또는 SchemaLibrary 항목을 가리키는 문서 간 $ref:)으로 JSON Schema 2020-12를 받습니다. 이들은 각 엣지의 구성에 대해 독립적으로 검증되는 엣지별 계약이며, 소비하는 Component 자체의 values 스키마에 합성되지 않습니다. 어떤 기둥에 대해 엣지별 스키마를 생략한 소켓은 그곳에 계약을 선언하지 않으며, 그 기둥에 작성된 구성은 검증되지 않습니다. 엣지별 구성은 닫힌 상태로 검증되며, 검증은 두 기둥 모두에서 기본값을 인식합니다. 스키마가 default:를 부여한 키는 작성자가 생략해도 제공된 것으로 간주됩니다.
선언된 default:는 두 기둥 모두에서 구체화되기도 합니다. 작성자가 생략한 키는 생략된 컴포넌트 value 또는 infra 키와 똑같이 선언된 기본값을 가진 채 소비하는 Recipe의 렌더 컨텍스트에 도달합니다. 따라서 소켓에 기본값을 선언하는 것으로 충분하며, Recipe 템플릿에는 이를 위한 대체 표현식이 필요 없습니다. 작성된 값은 항상 선언된 기본값보다 우선하며, 제공하는 키만 채웁니다. 소켓 계약의 키 하나를 작성한 엣지도 그 계약의 다른 키에 대해서는 선언된 기본값을 받습니다. 기본값은 엣지에 붙으므로, 연결되지 않은 소켓은 아무것도 기여하지 않습니다.
spec: usesSchema: databases: required: true selector: "datastore.aggrega.ai/engine=relational" inject: [env] valueSchema: # developer per-edge values, authored in the Aggregate pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 } tls_mode: { type: string, enum: [disable, require, verify-full], default: require } infraSchema: # operator per-edge infra, authored in the Release storage_class: { type: string, default: standard }그 소켓이 선언되어 있으면, Aggregate가 pool_size를 생략한 엣지는 10을 렌더링하고, Release가 storage_class를 생략한 엣지는 standard를 렌더링합니다. 작성은 각 기둥 안에서 키별로 우선합니다. pool_size: 42를 설정한 Aggregate는 42를 렌더링하면서 tls_mode는 여전히 require로 채워지며, storage_class: gp3를 설정한 Release는 어느 개발자 키도 건드리지 않고 gp3를 렌더링합니다.
소비하는 Component의 Recipe는 풍부화된 토폴로지 파이프에서 .context.uses.<alias>.values.<key>와 .context.uses.<alias>.infra.<key>로 해석된 엣지별 구성을 읽습니다. vocabulary/topology-triad.md를 참조하십시오.
각 연결이 채우는 슬롯 — 소켓의 featuresSchema. 소켓은 첨부 슬롯도 선언할 수 있으며, 그러면 소켓을 통해 연결된 모든 연결이 각 슬롯에 자신의 첨부를 가질 수 있습니다. 여러 모델에 도달하는 게이트웨이는 각 모델마다 다른 자격 증명을 보유하는데, 자격 증명이 게이트웨이가 아니라 연결에 있기 때문입니다.
spec: usesSchema: models: selector: "component.aggrega.ai/category=ai-model" featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: The credential the consumer presents to the component this connection reaches.연결은 자신의 features:에 슬롯 이름으로 어태치먼트를 담아 슬롯을 채웁니다. 이는 Aggregate의 연결 항목(Aggregate)이나 Release의 연결 항목(Release)에서 이루어지며, 해당 어태치먼트는 소비하는 컴포넌트의 어태치먼트 중 하나가 되어 <alias>.<slot>이라는 이름을 갖습니다.
이 선언이 하는 일을 정확히 기술하면 다음과 같습니다.
- 슬롯 이름은 닫힌 집합입니다. 어떤 이름으로든 자유 어태치먼트를 허용하는 Component 자체의
featuresSchema와 달리, 소켓의 슬롯은 그 소켓을 통한 연결이 담을 수 있는 유일한 이름입니다. 그 밖의 이름은 빌드 로드 시 중단되며,featuresSchema를 선언하지 않은 소켓은 연결에 어떤 어태치먼트도 허용하지 않습니다. 애드혹 소켓, 즉 이usesSchema가 선언하지 않은 소켓은 슬롯을 선언하지 않으므로 그 연결도 어태치먼트를 담지 않습니다. 각 연결은 자신의 슬롯을 스스로 채웁니다. 더 넓은 범위의 어태치먼트가 연결로 전파되는 일은 없으며, 연결 어태치먼트의 합성된 이름을 쓰는 Release 키는 중단됩니다. - 나머지 키는 각 연결을 슬롯에 맞춰 검사합니다. 여기서 슬롯은 Component 수준 슬롯과 같은 키
required,selector,inject,sensitive,description을 받으며, 각 연결은 개별적으로 이 키에 맞춰 검사됩니다.selector는 연결이 슬롯을 채우는 Feature의 레이블과 대조되며, 허용되지 않는 채움은 그 채움을 작성한 문서의 해당 연결 항목 위치에서 중단됩니다.required: true는 소켓을 통해 연결된 모든 연결에 적용됩니다. 슬롯을 비워 둔 연결은 해당 연결을 명시하며 중단되고, 그 옆에서 슬롯을 채운 연결은 통과합니다.sensitive는 Component 수준 슬롯에서와 똑같이 해석됩니다. 슬롯을 채우는 어태치먼트는 빌드 그래프와aggrega inspect에서 민감 정보로 표시됩니다. 컴포넌트에서와 마찬가지로 연결에서도 어태치먼트의 어떤 값이 민감 정보로 보류되는지는 오직 연결된 Feature 자체의 스키마가 결정합니다.inject는 슬롯의 내용을 전달하는 Workload 항목을 검사합니다. 연결의 어태치먼트는 자체inject:블록을 갖지 않으므로(어느 문서도 연결 항목에 이를 허용하지 않습니다) Workload는 슬롯과 함께 연결을 명시하여 이를 전달하며, 그 항목은 Component 수준 슬롯을 명시하는 항목이 그 슬롯의 허용 목록에 맞춰 검사되는 것과 똑같이 소켓 슬롯의 허용 목록에 맞춰 검사됩니다.
Feature의 usesSchema는 featuresSchema를 받지 않습니다. Feature가 만드는 연결은 어태치먼트를 담지 않으며, 소켓에 슬롯을 선언한 Feature는 로드 시 거부됩니다. 그러한 연결에 필요한 자격 증명은 Feature 자체 featuresSchema의 슬롯으로 둡니다.
usesSchema로부터의 스키마 생성. 컴파일러는 선언된 소켓으로부터 기본 JSON Schema 2020-12 조각을 생성하고 이를 사용자의 schema: 선언과 합성합니다. 이는 featuresSchema가 사용하는 것과 같은 패턴입니다. 생성된 스키마는 디스크에 기록되지 않으며 Component 검증 단계 동안 메모리에만 존재합니다. Aggregate에 있는 개발자의 uses: 맵은 병합된 스키마에 대해 검증되며, 소켓별 selector:는 정적 분석 중 노드 간 타입 안전성 검사로서 후보 Component 레이블에 대해 평가됩니다.
셀렉터 의미론: Split Schema 메커니즘. usesSchema[].selector:는 Aggrega의 토폴로지를 타입 없는 문자열 전달 이상의 것으로 만들어 줍니다. selector: "datastore.aggrega.ai/engine=vector"를 선언한 소켓은 일치하는 키-값 쌍으로 레이블된 Components로의 연결만 허용합니다. 에이전트가 자신의 primary_datastore 소켓을 relational Component에 연결하려 하면 명확한 셀렉터 위반 진단과 함께 Static Analyzer에서 실패합니다. 셀렉터는 Kubernetes 스타일의 레이블 셀렉터 문자열로, =, !=, in (...), notin (...), 단독 키, !key 형식에 대한 쉼표-AND 요구 사항으로 구성되며 Feature appliesTo가 사용하는 것과 같은 문법입니다. 문법은 vocabulary/modifier-system.md를, 엔진 의미론은 architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors”를 참조하십시오. 이 형식을 벗어난 요구 사항은 다른 셀렉터로 해석되지 않고 거부됩니다. 빈 요구 사항(앞, 뒤 또는 중복된 쉼표), 공백이나 =, !, (, ), 쉼표 중 하나를 포함한 키, 닫는 괄호가 없는 집합은 해당 소켓을 통해 엣지를 연결하는 모든 빌드를 해당 요구 사항을 명시하며 중단시킵니다. 따라서 프런트엔드를 제외하려는 소켓은 selector: "tier!=frontend"로 작성합니다. "!tier=frontend"는 거부되는데, !는 레이블 키만 지정하기 때문입니다.
애드혹 소켓: 소켓 선언으로 얻는 것과 선언 없이 작성자가 할 수 있는 것. Aggregate 작성자는 이 usesSchema가 선언하지 않은 소켓 이름으로 자신의 컴포넌트에 uses: 항목을 작성할 수 있으며, usesSchema를 전혀 선언하지 않은 Component에서도 마찬가지입니다. 엣지는 생성됩니다. 카탈로그가 어떤 소켓에 대해 침묵한다는 것은 그 연결이 예상되지 않았다는 뜻이지 금지되었다는 뜻이 아니며, 애플리케이션의 토폴로지는 개발자가 소유합니다.
이러한 애드혹 소켓이 포기하는 것은 정확히 선언된 소켓이 제공하는 것입니다. 그 모두가 usesSchema 항목에 있기 때문입니다. selector가 없으므로 엣지가 어떤 컴포넌트에 닿을 수 있는지 제약하는 것이 없고 노드 간 타입 안전성 검사는 평가할 대상이 없습니다. inject: 허용 목록도 없습니다. 엣지별 valueSchema도 없으므로 엣지별 values:는 검사받을 계약도, 상속할 선언된 기본값도 없습니다. infraSchema도 포기하지만, 어느 쪽이든 이러한 소켓에서는 그 계약에 도달하는 것이 없습니다. 엣지별 infra는 Release 엣지 항목에 작성되며, Release 항목은 소비하는 Component가 선언한 소켓만 명시할 수 있기 때문입니다. 변하지 않는 것은 엣지가 담을 수 있는 것입니다. 모든 inject 항목의 from:은 여전히 대상 Component의 schema.provides가 선언한 키를 명시해야 하며 대상은 여전히 존재해야 합니다. 둘 다 선언된 소켓에서와 마찬가지로 빌드를 중단시킵니다.
“inject: 허용 목록 없음”은 블랙박스 선언이 아니라 제약의 부재로 읽어야 합니다. 두 가지는 겉보기에는 비슷하지만 정반대로 동작하기 때문입니다. 애드혹 소켓을 통한 엣지는 전달 방식을 자유롭게 지정할 수 있습니다. 메커니즘이 벗어날 허용 목록이 없고, 값을 내부적으로 처리하겠다고 약속한 엔티티도 없습니다. 위의 블랙박스 거부는 엔티티가 실제로 선언하고 inject: 허용 목록 없이 둔 소켓에 적용됩니다. 그 생략은 엔티티가 예상한 연결에 대한 진술이며, 애드혹 소켓은 그러한 진술을 하지 않습니다.
전달 경로는 동일하며, 렌더링된 아티팩트에는 차이가 기록되지 않습니다. 애드혹 엣지의 inject 블록은 선언된 소켓의 것과 똑같이 해석되고 전달됩니다. 각 from: 키는 대상의 평가된 provides에서 읽혀 작성자가 선택한 전달 키로 소비 노드의 주입 컨텍스트에 놓이고, 거기서 렌더링된 아티팩트에 도달합니다. 전달 경로는 하나이며, 그 위의 어떤 것도 소켓이 선언되었는지에 따라 분기하지 않습니다. 선언된 소켓이 추가할 수 있는 것은 내용, 즉 valueSchema나 infraSchema가 채우는 엣지별 기본값입니다. 따라서 선언된 소켓에 그러한 계약이 없는 경우, 같은 엣지는 어느 종류의 소켓에서든 동일하게 렌더링됩니다. 선언은 연결에 관한 사실이지, 렌더링되는 것에 대한 입력이 아닙니다.
애드혹 소켓의 엣지별 values:는 허용되어 .context.uses.<alias>.values에서 소비하는 Recipe에 검증되지 않은 채로 도달합니다. 비교할 valueSchema가 없으므로 어떤 키도 검사되지 않고 거부되지도 않습니다. 이는 애드혹 소켓에만 해당하는 것이 아닙니다. 해당 축에 대한 계약을 작성하지 않은 선언된 소켓도 엣지별 구성을 같은 방식으로 다룹니다. 애드혹 소켓이 바꾸는 점은 소켓을 선언하지 않고는 계약을 추가할 수 없다는 것입니다. 이러한 엣지에서 .context.uses.<alias>.infra는 비어 있습니다. 엣지별 infra를 공급하는 표면이 선언되지 않은 소켓을 명시할 수 없기 때문입니다.
내보낸 그래프의 모든 에지는 자신이 둘 중 어느 쪽인지 기록하므로 소비자가 이를 추론할 필요가 없으며, 모든 연결이 선언된 소켓을 거치기를 원하는 조직은 이를 거버넌스 정책으로 요구할 수 있습니다. 여기서 소켓을 선언하는 것이 여전히 더 나은 방법이며, 표준 라이브러리 카탈로그도 그렇게 합니다. 선언된 소켓은 에지가 도달할 수 있는 component를 제한하는 selector, inject: 허용 목록, 자체 기본값을 갖춘 에지별 계약, 그리고 설명을 지닙니다. 이는 예상된 연결에 대한 검토 가능한 진술로서, 그것을 만드는 엔터티와 함께 버전이 관리됩니다. 애드혹 형식은 탈출구이지 새로운 기본값이 아닙니다. 두 표면은 의도적으로 이런 방식으로 열려 있지 않습니다. Feature 첨부의 uses는 첨부된 Feature가 선언한 소켓만 지정할 수 있고, Release의 에지별 uses는 소비하는 Component가 선언한 소켓만 지정할 수 있습니다.
작업 예제 examples/adhoc-uses-socket/는 하나의 소비자에 두 종류의 에지를 모두 구성하고, 렌더링된 출력에서 전달된 두 값을 나란히 보여 주며, 선언되지 않은 from: 키가 일으키는 중단도 함께 보여 줍니다.
소켓 이름 오타는 중단이 아니라 권고로 드러납니다. 선언되지 않은 소켓 이름은 합법이므로, 철자가 틀린 소켓 이름은 작성자가 의도한 소켓을 연결하는 대신 그 자체로 애드혹 연결이 됩니다. 그리고 그 위로 아무것도 흐르지 않는 동안에도 빌드는 성공 상태를 유지합니다. 컴파일러는 이 usesSchema가 선언한 이름과 편집 거리 1 이내인 소켓 이름을 두 철자를 모두 명시하는 경고로 보고합니다. errors/warnings.md의 “Uses-socket near-miss lint”를 참조하십시오. 이 경고는 빌드 판정을 결코 바꾸지 않으며, 컴파일러는 작성자가 소켓 이름을 무엇으로 짓는지 단속하지 않습니다.
usesSchema와 featuresSchema의 관계. 둘 다 선언적 테이블이며 둘 다 동일한 의미의 inject: 허용 목록을 지니지만, 소켓과 슬롯은 서로 다른 것이며 서로 바꿔 쓸 수 없습니다. usesSchema는 component 간 에지, 즉 토폴로지 그래프를 관장하며 어떤 소켓이 계약을 지니는지 선언합니다. featuresSchema는 첨부 슬롯을 관장하며, 슬롯은 열거가 아니라 이름이 붙은 바인딩 지점입니다. 어떤 슬롯도 선언하지 않은 이름의 첨부는 component 자체 블록에서 합법입니다. (소켓이 자신의 연결에 대해 선언하는 슬롯은 유일하게 닫힌 집합이며, 이는 위의 “Slots each connection fills”에서 설명한 바와 같습니다.) 두 표면은 이 점에서 수렴했습니다. 선언되지 않은 소켓 이름 아래의 component 자체 uses: 항목도 합법입니다. 그러나 둘은 여전히 구별됩니다. 선언되지 않은 슬롯은 선언된 슬롯에 영향을 주지 않는 Component 위의 자유 첨부인 반면, 선언되지 않은 소켓은 selector도 에지별 계약도 없는 에지입니다. 많은 Components가 둘 다 선언하며, 두 테이블은 독립적으로 구성됩니다.
부착 슬롯: featuresSchema
Component는 featuresSchema 블록을 통해 부착 슬롯을 선언할 수 있습니다. 각 슬롯은 Component가 Feature의 부착을 기대하는 바인딩 지점(루트 비밀번호, API 키, 인증 토큰, ID 바인딩)에 이름을 붙이고, 어떤 Feature가 그 슬롯을 바인딩할 수 있는지와 채움의 자료를 어떻게 전달할 수 있는지를 제약합니다.
이 절은 Component 자체의 슬롯을 다룹니다. 소켓이 각 연결에 대해 선언하는 슬롯은 이와 달리 닫힌 집합입니다. Topology Sockets 아래의 “Slots each connection fills”를 참조하십시오.
슬롯을 선언해도 부착 표면이 닫히지는 않습니다. 작성자는 어떤 슬롯도 선언하지 않은 이름으로 Feature를 부착할 수 있으며, 그 부착은 자유 부착입니다. 완전히 적법하며, 단지 선언된 슬롯에 바인딩되지 않을 뿐입니다. 이러한 개방성 덕분에 하나의 카탈로그 엔터티가 카탈로그를 포크하지 않고도 서로 다른 두 가지 배포 형태를 지원할 수 있습니다.
- 소비자별. 각 인스턴스가 자체 Feature로 슬롯을 채우므로, 각 소비자는 자체적으로 렌더링된 자격 증명을 받습니다.
- 공유. 어떤 인스턴스도 슬롯을 채우지 않습니다. 대신 하나의 자격 증명이 더 넓은 범위(서브시스템 또는 Release 경계)에 한 번 부착되어 그 아래의 모든 컴포넌트로 전파되므로, 모든 소비자가 그 하나의 선언으로부터 채워집니다. 무엇이 렌더링되는지는 실현 방식에 따릅니다. Secret을 렌더링하는 실현 방식에서는 소비자마다 동일한 자료를 담은 Secret이 하나씩 생기고, 모든 소비자가 이미 존재하는 Secret을 가리키게 하는 실현 방식에서는 아무것도 렌더링되지 않습니다.
작성자는 무엇을 부착하는지에 따라 둘 중 하나를 선택합니다. 카탈로그 엔터티는 두 경우 모두 동일합니다.
이 열린 표면에서 빌드를 중단시키는 형태가 하나 있습니다. 바로 컴포넌트에 다른 이름으로 작성된 채움입니다. 컴포넌트 자체에 작성된 부착(Aggregate 안의 자체 features: 블록 또는 해당 컴포넌트에 대한 Release의 항목)이 어떤 슬롯도 선언하지 않은 이름을 가지고 있고, 그 Feature가 모든 범위가 병합된 후 해당 컴포넌트에서 아무것도 바인딩하지 않은 슬롯의 selector를 충족하면 빌드가 중단됩니다. 이는 슬롯을 위한 채움이 잘못된 이름으로 작성되었을 때 취하는 형태입니다. 그대로 두면 슬롯은 빈 채로 남고 그 부착은 자유 부착이 되며, 비어 있는 선택적 슬롯은 빌드가 성공하면서도 아무것도 전달하지 않습니다. 메시지는 부착, 컴포넌트, Feature, 그리고 그 Feature가 들어맞는 각각의 빈 슬롯을 명시하며, 해결 방법은 슬롯의 이름으로 부착하는 것입니다. 이는 자격 증명뿐 아니라 모든 Feature에 적용됩니다. 표면의 나머지는 모두 자유롭게 유지됩니다. Feature가 선언된 어떤 슬롯에도 들어맞지 않는 부착, 들어맞는 모든 슬롯이 바인딩된 후의 추가 부착, 그리고 컴포넌트가 서브시스템이나 Release 경계로부터 상속하는 부착이 그렇습니다. 따라서 위의 공유 형태는 영향을 받지 않습니다. selector를 선언하지 않은 슬롯은 어떤 Feature를 위한 것인지 아무것도 말하지 않으므로, 어떤 부착도 이런 방식으로 그 슬롯에 묶이지 않습니다. 이 중단은 errors/fatal-halts.md의 “An attachment written under another name fits a slot its component leaves empty(다른 이름으로 작성된 부착이 컴포넌트가 비워 둔 슬롯에 들어맞음)” 아래에 설명되어 있습니다.
두 형태는 조합되며, 더 가까운 쪽이 우선합니다. 작성자는 두 가지를 동시에 할 수 있습니다. 더 넓은 범위에 Feature를 부착하여 그 범위 아래의 모든 컴포넌트에 도달하게 하고, 다른 것이 필요한 하나의 컴포넌트에서 슬롯을 채우는 것입니다. 컴포넌트 범위의 채움이 필드 단위로 우선하므로, 변경하는 필드만 다시 명시하면 되고 나머지는 여전히 더 넓은 부착에서 가져옵니다. 슬롯을 채우지 않은 형제 컴포넌트는 더 넓은 부착을 그대로 유지합니다. 어노테이션 기반 부착 및 조합된 Aggregates와의 상호 작용을 포함한 전체 우선순위 규칙은 vocabulary/labels-and-annotations.md의 “Attachment precedence”에 있습니다.
Component의 스키마 정의:
spec: featuresSchema: root_password: inject: [] description: Root database password. Recipe controls delivery (Black-Box). user_password: inject: [env, file] description: Application user password, auto-generated if omitted. replication_password: inject: [] description: Replication password for HA setups.필드 의미:
| 필드 | 타입 | 기본값 | 의미 |
|---|---|---|---|
required | bool | false | 슬롯이 최종적으로 바인딩되어야 함을 선언합니다. 이 Component의 인스턴스에서 슬롯의 이름을 아무것도 바인딩하지 않으면 빌드가 중단되며, 이는 전체 부착 전파 후 인스턴스가 보유한 부착 집합을 기준으로 검사됩니다. 따라서 인스턴스가 상속하는 범위에서 선언된 부착은 인스턴스 자체에 작성된 채움과 똑같이 슬롯을 충족합니다. 진단은 컴포넌트와 슬롯을 명시합니다. |
inject | string[] | — | 허용되는 inject 전달 메커니즘의 허용 목록입니다. [](빈 목록)는 블랙박스를 의미합니다. Recipe가 내부적으로 전달을 제어하며 자료는 워크로드에 전달되지 않습니다. [env, file]는 투명을 의미합니다. 채움의 자료가 나열된 메커니즘을 통해 전달될 수 있습니다. usesSchema[].inject와 의미가 같습니다. |
description | string | — | 사람을 위한 문서로, IDE와 허브에서 렌더링됩니다. |
selector | string | — | 어떤 Feature가 이 슬롯을 채울 수 있는지 제약하는 선택적 Kubernetes 스타일 레이블 셀렉터입니다. usesSchema 소켓의 selector에 대응하는 슬롯 버전으로, 같은 문법과 같은 네이티브 레이블 매칭 엔진을 사용합니다. 정적 분석 중에 부착된 Feature 자체의 레이블을 기준으로 평가됩니다. 레이블이 이를 충족하지 않는 채움은 빌드를 중단시키며, 문법이 거부하는 셀렉터도 읽지 못한 요구 사항을 명시하며 빌드를 중단시킵니다. 채움에 제약을 두지 않으려면 생략합니다. |
sensitive | bool | false | 이 슬롯을 바인딩하는 것이 무엇이든 비밀 자료를 다룬다고 선언합니다. 특정 채움이 아니라 바인딩 지점에 관한 진술입니다. 아래의 “Declaring a slot sensitive”를 참조하십시오. |
슬롯은 채움이 무엇을 구성하는지가 아니라 어떤 채움이 슬롯을 바인딩할 수 있는지를 제약합니다. 슬롯 수준의 values 또는 infra 계약은 의도적으로 없습니다. 부착된 Feature 자체의 schema:가 해당 영역을 소유하므로, 각 계약은 정확히 하나의 위치를 가집니다.
슬롯 selector는 Component가 FeatureRecipe를 명시하지 않고 어떤 Feature가 슬롯을 채울 수 있는지 좁히는 방법입니다. 예를 들어 프로바이더별 자격 증명 Feature(feature.aggrega.ai/kind=secret, provider=helm)로 좁힐 수 있으며, 이는 usesSchema 소켓 셀렉터가 종속성 엣지의 대상을 좁히는 것과 정확히 같습니다. 컴파일러는 부착된 Feature의 레이블만을 기준으로 셀렉터를 평가합니다. 채움이 가진 레이블을 읽고, 셀렉터가 그것을 허용하는지 보고합니다. 어떤 레이블을 요구하는 것이 의미 있는지는 카탈로그 작성 시의 선택이며, 컴파일러가 부과하는 규칙이 아닙니다.
슬롯 이름 오타는 중단이 아니라 권고로 표시됩니다. 선언되지 않은 부착 이름은 적법하므로, 철자가 틀린 슬롯 이름은 작성자가 의도한 슬롯을 채우는 대신 자유 부착이 됩니다. 컴파일러는 선언된 슬롯 이름과 편집 거리 1 이내인 부착 이름을 두 철자를 모두 명시하는 경고로 보고합니다. errors/warnings.md의 “Attachment-slot near-miss lint”를 참조하십시오. 이 경고는 빌드 결과를 바꾸지 않습니다. 컴파일러는 작성자가 부착에 어떤 이름을 붙이는지 단속하지 않습니다. 부착의 Feature가 selector를 충족하는 슬롯과 편집 거리 1인 이름에는 경고가 표시되지 않습니다. 그 슬롯이 결국 비어 있으면 위에서 설명한 중단이 대신 그 부착을 보고하고, 다른 무언가가 슬롯을 바인딩하면 그 부착은 일반적인 추가 부착이 됩니다.
슬롯을 민감하다고 선언하기
슬롯의 sensitive: true는 소비자 자신의 요구를 나타냅니다. 이 지점에 바인딩되는 것은 무엇이든 비밀 자료를 다룹니다.
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: "Optional database password credential."이는 스키마 리프의 sensitive: true와 실제로 다른 정보이며, 편의상 중복된 것이 아닙니다. 표준 라이브러리 카탈로그에는 둘 다 필요합니다. 참조 가능한 자격 증명은 provides.name과 provides.key, 즉 리소스의 위치 지정자와 그 안의 데이터 키를 게시하며, 어느 것도 민감하지 않습니다. Kubernetes Secret의 이름은 공개이고 그 안의 키도 마찬가지입니다. 그러나 그 자격 증명이 채우는 슬롯은 분명히 비밀 자료를 다룹니다. 리프는 이 데이터는 비밀 자료다라고 말하고, 슬롯은 이 바인딩 지점은 비밀 자료를 다룬다라고 말합니다. 두 주장은 서로 다른 대상에 관한 것이며 독립적으로 성립할 수 있습니다.
실질적인 결과는 요구가 채움이 아니라 바인딩 지점과 함께 이동한다는 것입니다. 대상 엔진이 자격 증명을 소유하고 작성자가 아무것도 작성하지 않기 때문에 민감한 리프를 전혀 선언하지 않는 Feature도, 슬롯이 그렇게 선언했으므로 민감한 슬롯을 민감한 첨부로 바인딩합니다. 반대도 성립합니다. 민감한 리프를 선언하는 채움은 그런 선언을 하지 않은 슬롯을 바인딩하거나 어떤 슬롯도 바인딩하지 않는 자유 첨부인 경우에도 민감한 첨부입니다.
이 선언은 작성된 특정 블록이 아니라 첨부 캐스케이드를 따릅니다. 슬롯의 요구는 모든 범위가 접힌 후 최종적으로 바인딩되는 채움에 적용되므로, 더 넓은 범위의 채움을 대체하는 컴포넌트 수준 채움은 그 요구를 그대로 물려받습니다.
슬롯의 sensitive는 리프 수준 키워드와 같은 한계를 가집니다. 주석을 달 뿐이며, 암호화하거나 검증하거나 거부하거나 전달 메커니즘을 강제하거나 렌더링된 바이트를 변경하지 않습니다. 전체 설명은 vocabulary/compact-form-authoring.md의 “What the keyword does not do”에 있습니다.
sensitive와 compliance.aggrega.ai/data-class는 서로 다른 두 축이며, 나란히 문서화되고 결코 혼동되지 않습니다. sensitive는 하나의 리프 또는 하나의 슬롯에 대한 불리언입니다. 이 데이터 또는 이 바인딩 지점은 비밀 자료를 다룬다. compliance.aggrega.ai/data-class는 노드 전체에 붙는 등급 레이블(public, internal, restricted)로, 컴포넌트가 보유한 데이터에 거버넌스 정체성을 부여합니다. 하나는 데이터별이며 이진적이고, 다른 하나는 노드별이며 순서가 있습니다. 어느 것도 다른 것을 대신하지 않으며, 엔터티는 둘 다 가질 수 있습니다. 이 레이블은 vocabulary/labels-and-annotations.md와 architecture/08-credential-model.md의 “Data governance around credentials”에서 다룹니다.
featuresSchema로부터의 스키마 투영
선언된 슬롯은 첨부 블록의 형태를 기술하는 JSON Schema 2020-12 프래그먼트로 투영됩니다. 이에 대해 검증되는 채움은 두 종류입니다. 가져온 모듈이 제공하는 컴포넌트의 첨부 블록은 그 모듈을 가져오는 컴포지션이 빌드된 후에 검증되고, 더 넓은 범위에서 선언된 첨부는 그것이 도달하는 각 컴포넌트의 슬롯에 대해 검증됩니다. Aggregate 자체가 선언하는 컴포넌트의 첨부 블록은 대신 Aggregate의 문서 스키마와 슬롯의 inject 허용 목록으로 판단되며(아래 참조), 프래그먼트는 어떤 채움에 대해서도 둘이 같은 판정에 이르도록 구성되어 있습니다. 투영은 디스크에 기록되지 않고 메모리에만 존재하며, Component의 schema:는 첨부 필러를 직접 작성할 필요가 없습니다.
입력 featuresSchema:
featuresSchema: root_password: inject: [] user_password: inject: [env, file]투영된 프래그먼트(메모리 내, 축약형 표현):
# The OUTER object is open: an attachment under a name no slot declares is# admitted, because a free attachment is legal authoring.root_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true # inject admits only an empty block — inject: [] means the Recipe controls # delivery, so a fill may name no mechanism inject: {}user_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true inject: env: { type: array } file: { type: array } # arg is absent — not in the inject allowlist두 깊이는 독립적입니다. 외부 객체는 열려 있으므로, 선언된 슬롯이 엔터티가 열거하지 않은 첨부를 금지하지 않습니다. 각 선언된 슬롯의 자체 프래그먼트는 닫혀 있으므로, 선언된 슬롯을 실제로 바인딩하는 채움은 여전히 그 슬롯의 형태로 제약됩니다.
이 프래그먼트는 형태만 기술합니다. 어떤 슬롯이 바인딩되어야 하는지에 대해서는 아무것도 말하지 않는데, required로 표시된 슬롯은 더 넓은 범위에서 캐스케이드되어 들어오는 첨부로 바인딩될 수 있고, 그러면 이 프래그먼트가 기술하는 블록은 비게 되기 때문입니다. 따라서 요구 사항은 특정 블록이 선언하는 내용이 아니라 컴포넌트가 최종적으로 갖게 되는 첨부 집합에 대해 검사되며, 작성된 블록에는 두 질문 중 하나만 제기되므로 둘은 서로 모순되지 않습니다.
허용되는 키는 첨부가 어디서든 가질 수 있는 키를 그대로 반영하므로, 자유 첨부에서 유효한 키는 슬롯 채움에서도 유효합니다. 허용 목록에 있는 각 전달 메커니즘은 전달 항목의 목록이며, 이는 inject:가 어디서나 취하는 형태와 같습니다. 슬롯은 어떤 메커니즘 이름이 나타날 수 있는지를 좁힐 뿐, 항목의 모양을 좁히지 않습니다.
inject 허용 목록이 적용되는 곳
허용 목록은 슬롯의 양쪽을 서로 다른 두 단계에서 구속합니다.
렌더링 단계에서 Recipe의 Workload에 대해: 컨테이너 첨부 항목을 통해 슬롯을 참조하는 Workload는 엔터티가 선언한 슬롯을 지정해야 하며, 슬롯의 inject 허용 목록이 허용하는 전달 메커니즘을 선택해야 합니다. 블랙박스 슬롯(inject: []), 허용 목록 밖의 메커니즘, 또는 엔터티가 선언하지 않은 슬롯을 참조하면 빌드가 중단됩니다. 진단 메시지는 Recipe, 컨테이너 경로, 문제가 된 슬롯을 지정하며, 카탈로그 결함으로 분류됩니다. 잘못한 것은 Recipe이기 때문입니다.
첨부가 해석될 때 그리고 렌더링 전에 Aggregate 자체의 첨부에 대해: 선언된 슬롯을 바인딩하는 채움의 inject: 블록은 슬롯의 허용 목록이 허용하는 메커니즘만 지정할 수 있으며, 블랙박스 슬롯은 아무것도 허용하지 않습니다. 비어 있는 허용 목록은 “Recipe가 이를 내부적으로 전달하므로 전달 방식을 지시하지 마십시오”라는 뜻이며, 이에 대한 전달을 작성하면 빌드가 중단됩니다. 진단 메시지는 첨부 위치에 표시되며 슬롯과 문제가 된 메커니즘, 그리고 슬롯이 허용하는 메커니즘이 있으면 그것도 함께 지정합니다. 잘못한 것은 Aggregate이므로 개발자 결함으로 분류됩니다. 빈 inject: {} 블록은 어떤 메커니즘도 지정하지 않으므로 전달을 지시하지 않으며, 블랙박스 슬롯을 포함한 모든 슬롯에서 허용됩니다. 이는 Aggregate가 선언하는 컴포넌트, 가져온 모듈이 제공하는 컴포넌트, 더 넓은 범위에서 선언된 첨부 모두에 똑같이 적용됩니다. 자유 첨부, 즉 어떤 슬롯도 선언하지 않은 이름의 첨부에는 이런 제약이 없습니다. 허용 목록은 블록이 아니라 슬롯에 속하기 때문입니다.
컴파일 파이프라인 전반의 종단 간 흐름, 즉 Aggregate 첨부가 자격 증명 Feature(예: core/secret-value)에 연결되고 이어서 실행 중인 워크로드에 자격 증명을 전달하는 프로바이더별 FeatureRecipe에 연결되는 방식은 examples/05-credential-features에서 단계별로 다룹니다.
호출자가 제시하는 키와 서버가 검증하는 키
한 component가 키를 검사하는 다른 component를 호출하는 경우, 양쪽 끝은 각자 자기 쪽에서 키를 보유하며, 스스로 선언한 slot에 둡니다. 이는 표준 라이브러리 카탈로그가 따르는 관례이며, 컴파일러는 이 중 어느 것도 강제하지 않습니다. 컴파일러는 각 component의 slot을 그 component 자신의 attachment와 대조해 검사하고, 그 문자열을 그대로 전달할 뿐, 한 component가 보유한 것을 다른 component가 보유한 것과 비교하지 않습니다.
- 호출자가 제시하는 키는 호출자의 것입니다. 이 키는 호출자의 socket이 각 연결마다 선언하는 slot에 있으므로(위의 “각 연결이 채우는 slot” 참조), 여러 대상에 도달하는 호출자는 대상마다 키를 하나씩 보유합니다.
core/ai-agent/crewai의modelsocket은 그 slot을credential로 선언하며, 그 Recipes는 이를 채우는 값을 무엇이든OPENAI_API_KEY로 전달합니다.core/gateway/litellm,core/gateway/kong,core/gateway/apisix의modelssocket도 이를 선언하며, 그 Recipes는 각 연결의 키를 연결의 별칭을 따라 이름 붙인 고유한 변수로 전달하므로, 게이트웨이가 제공하는 모든 모델이 각자의 키를 보유합니다. 대신 Component가 자신의 slot에 선언한 키는 그 Component가 만드는 모든 연결에 대해 하나의 키입니다. - 서버가 검증하는 키는 서버 자신의 slot입니다.
core/ai-model/vllm,core/ai-model/tei,core/ai-model/tgi는 각각 선택적인api_key를 선언하며, 각 Recipes는 이를 채우는 값을 무엇이든 서버가 키를 읽어 오는 변수로 전달합니다. LiteLLM 모델과 게이트웨이는 LiteLLM이 마스터 키라고 부르는 키를 위해api_key를 선언합니다. - 어느 쪽 끝도 상대의 attachment를 보지 못합니다. 연결 위의 attachment는 호출자의 attachment 중 하나로서 호출자의 렌더링에만 도달하며, 서버의 렌더링 출력은 서버에 도달하는 연결이 무엇을 담든 동일합니다.
required로 표시된 slot은 그것을 선언한 component가 채워야 할 책임이 있으며, 그에 연결된 component들의 책임이 아닙니다. 또한 한쪽 끝의 slot을 채워도 다른 쪽에는 아무것도 채워지지 않으므로, 양쪽 끝에 키를 선언하는 것은 중복이 아니라 최소 요건입니다. - 양쪽 끝은 하나의 parameter를 읽으므로, 호출자가 제시하는 키와 서버가 검증하는 키가 서로 다르게 작성될 수 없습니다.
# Aggregate fragment — one parameter feeds both endsspec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key agent: type: core/ai-agent/crewai # values (role, goal, backstory, …) elided uses: model: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key하나의 키를 검사하는 서버는 호출자들을 구별할 수 없습니다. vLLM, TEI, TGI는 각각 단일 키를 검사하므로, 서버에 도달하는 연결이 몇 개이든 모든 호출자가 같은 키를 제시합니다. 양쪽 끝이 하나의 secret을 참조할지 각자 자신의 secret을 보유할지는 각 provider가 참조로 secret을 해석하는 위치에 따라 정해지며, 각 끝의 실현 방식은 Manifest가 선택합니다. Credential Model에서 두 경우를 모두 다룹니다.
component가 자기 자신을 위해 보유하는 자격 증명(예: 자신의 세션에 서명하는 키)은 다른 것과 마찬가지로 자신의 featuresSchema:의 slot입니다. socket 중 하나를 통해 도달하는 데이터 저장소에 제시하는 비밀번호는 위에서 말한 호출자의 키이므로, 해당 연결 위에 credential로 둡니다. core/gateway/kong의 backend socket이 이를 선언하고 그 workload 합성 Recipes가 이를 KONG_PG_PASSWORD로 전달하며, core/gateway/litellm의 cache_store socket은 시맨틱 캐시가 저장소에 제시하는 비밀번호를 위해 이를 선언하고 REDIS_PASSWORD로 전달합니다. 하나의 연결이 액세스 키 식별자와 그 secret이라는 쌍을 제시하는 경우, core/ai-agent/agenta-api의 store socket처럼 secret 쪽은 credential, 식별자 쪽은 credential_id입니다.
셀프 주입: spec.inject
Component는 셀프 주입 전달 메커니즘을 허용 목록으로 지정하는 최상위 spec.inject: 배열을 선언할 수 있습니다. 이 배열이 있으면 개발자는 Aggregate의 컴포넌트 수준에서 inject: 블록을 사용하여 Component 자신의 values: 또는 provides: 키를 자신의 전달 파이프(컨테이너의 환경 변수, 마운트된 파일 또는 프로세스 인수)에 직접 주입할 수 있습니다. spec.inject:가 없거나 비어 있으면 컴포넌트 수준의 셀프 주입은 금지됩니다. 이 경우 Recipe가 모든 내부 연결을 제어하며, 이는 usesSchema[].inject: []와 featuresSchema[].inject: []가 각각 컴포넌트 간 전달과 자격 증명 전달에 적용하는 블랙박스 패턴과 일치합니다.
# Component declares its self-inject allowlist:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/web-server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: inject: [env, file] schema: values: log_level: { type: string, default: info } tls_enabled: { type: boolean, default: false } provides: health_endpoint: { type: string }# Aggregate fragment — developer dictates self-inject delivery:components: api: type: core/web-server values: log_level: debug tls_enabled: true inject: env: - in: LOG_LEVEL value: '{{"{{"}} .values.log_level }}' - in: TLS_ENABLED value: '{{"{{"}} .values.tls_enabled }}' file: - in: /etc/web/health-probe from: health_endpoint각 value: 템플릿은 {{가 아니라 {{"{{"}}로 시작합니다. Aggregate의 전체 텍스트는 셀프 주입 해석이 실행되기 전에 매개변수 보간을 위해 템플릿으로 한 번 읽히며, 그 시점에는 .values가 존재하지 않습니다. 이 이스케이프는 셀프 주입 해석이 평가할 수 있도록 {{를 되돌려 놓습니다. 자체 이중 중괄호를 포함하는 텍스트를 참조하십시오.
필드 의미. spec.inject:는 메커니즘 이름의 배열입니다. 세 가지 값이 정의되어 있습니다.
env— 컨테이너의 환경 변수.file— 마운트된 파일 경로.arg— 프로세스 명령줄 인수.
의미는 usesSchema[].inject 및 featuresSchema[].inject와 정확히 같습니다. 어휘가 같고, 생략 시 같은 블랙박스 패턴이 적용되며, Aggregate 측의 작성 형태도 같습니다. 차이는 출처입니다. usesSchema[].inject는 컴포넌트 간 의존성의 provides가 소비자의 전달 파이프로 흘러드는 방식을, featuresSchema[].inject는 자격 증명이 컨테이너에 도달하는 방식을, spec.inject는 Component 자신의 values와 provides가 Component 자신의 컨테이너에 도달하는 방식을 제어합니다.
작성 원칙. spec.inject: [env, file]을 선언한 core/web-server Component는 투명한 전달을 선택합니다. 즉 Aggregate 작성자가 어떤 환경 변수 이름이 어떤 값을 전달할지 지정합니다. spec.inject: []를 선언한(또는 필드를 생략한) Component는 전달을 불투명하게 유지합니다. 즉 Recipe의 valuesMapping:이 어떤 필드가 어떤 컨테이너 변수로 흘러갈지 결정하며, 개발자는 Aggregate에서 이를 재정의할 수 없습니다. 블랙박스 패턴은 안정적인 계약 Components에 적합하고(Recipe가 DB 비밀번호를 POSTGRES_PASSWORD 환경 변수에 연결하는 방법을 아는 core/postgres-db Component), 투명한 패턴은 개발자의 의도가 정당하게 전달 세부 사항을 지정하는 Components에 적합합니다(애플리케이션이 개발자가 사용자 지정하려는 비표준 변수 이름에서 LOG_LEVEL을 읽는 core/web-server).
오류 모드. spec.inject:가 없거나 비어 있는 Component에 inject: 블록을 사용하는 개발자의 Aggregate는 워크스페이스 로드 시 빌드를 중단합니다(“Self-inject on a component without an allowlist (허용 목록이 없는 컴포넌트의 셀프 주입)”). 허용 목록에 없는 메커니즘을 사용하는 inject: 블록은 같은 조건으로 중단되며, 그 메커니즘과 허용 목록이 허용하는 메커니즘을 명시합니다(“Self-inject mechanism not in the component’s allowlist (컴포넌트의 허용 목록에 없는 셀프 주입 메커니즘)”). 셀프 주입, 컴포넌트 간 주입, 자격 증명 주입 사이의 전달 키 충돌도 중단됩니다(“Duplicate delivery key across inject sources (주입 소스 간 중복 전달 키)”). 오류별 메시지 형태는 errors/fatal-halts.md를 참조하십시오.
카탈로그 작성: 기본 Components 확장
플랫폼 아키텍트는 extends 키워드를 사용하여 기업 또는 커뮤니티 기준선 위에 특화된 인터페이스를 겹쳐 올립니다. 확장은 구조를 합성하고 데이터 축은 통째로 상속합니다. 컴파일러는 기본에서부터 아래로 체인을 따라가며, 두 부분은 서로 다르게 동작하고, 그 차이가 곧 작성 모델의 전부입니다.
확장이 합성하는 것. 다음 영역은 체인을 따라 병합되며, 키마다 확장하는 Component가 우선하고 목록은 중복 없이 기본 쪽부터 이어 붙습니다.
| 보고 위치 | 합성 방식 |
|---|---|
metadata.labels | 키별로 병합되며, 공유 키에서는 확장하는 Component의 값이 우선합니다 |
metadata.annotations | 키별로 병합되며 우선순위도 같습니다. 이 때문에 기본의 존재 의무가 그것을 확장하는 모든 Component에 전달됩니다 |
spec.featuresSchema | 부착 슬롯의 합집합이며, 확장하는 Component가 다시 선언한 슬롯은 기본의 같은 이름 항목을 대체합니다 |
spec.usesSchema | 토폴로지 소켓의 합집합이며, 이름별 대체 규칙도 같습니다 |
spec.inject | 두 자체 주입 허용 목록이 이어 붙으며, 기본 항목이 먼저 오고 중복은 제거됩니다 |
spec.assertions | 명명된 규칙이 누적되며 기본 규칙이 먼저 옵니다. 이 영역만은 이름별 대체를 허용하지 않습니다. 아래의 “어서션 상속은 누적적입니다”를 참조하십시오 |
확장하는 Component가 추가하는 소켓은 에지별로 자체 valueSchema와 infraSchema를 가질 수 있습니다. 이는 해당 소켓의 에지에 대한 계약이며, Component 자체의 축에 추가되는 것이 아닙니다.
metadata:의 나머지는 그것을 선언한 문서에 남습니다. 체인을 따라 내려가는 메타데이터는 labels와 annotations뿐입니다. name, version, description, maintainers, license, repository, home, keywords는 확장하는 Component 자신의 것이며, 작성된 그대로 읽힙니다. description:을 생략한 Component는 기본의 것을 빌리지 않고 설명이 없는 상태가 됩니다. 식별 정보와 출처는 지금 읽고 있는 문서에 속하므로, 래퍼가 그것이 감싸는 대상으로 오인되는 일은 없습니다.
확장이 통째로 상속하는 것. 세 데이터 축인 values, infra, provides는 합성되지 않습니다. 확장하는 Component는 축 내용을 작성하지 않습니다. 리터럴 표시 schema: inherited를 쓰고, 기본이 작성한 그대로의 schema: 블록을 받습니다. 깊이와 관계없이 체인의 모든 Component는 체인 루트의 블록을 변경 없이 가지므로, 말단에서 aggrega inspect --resolved를 실행하면 루트와 같은 축이 표시됩니다.
게시된 Component 스키마는 가능한 세 가지 결과 중 어느 것이 유효한지 정하며, 나머지 둘은 문서를 로드할 때 거부합니다. 서로 다른 실수이므로 각각 다른 진단이 나옵니다.
- **
schema:아래에 축 내용이 있는extends:**는 거부됩니다. Component의 계약은 기본의 계약이며, 두 번째의 다른 계약이 존재할 곳은 없습니다. - **
schema:를 완전히 생략한extends:**는 거부됩니다. 생략하면 읽는 사람이 상속된 축 블록과 빠뜨린 축 블록을 구별할 수 없습니다. - **
extends:없는schema: inherited**는 거부됩니다. 이 표시는 축을 어디서 가져오는지를 나타내는데, 이 Component에는 가져올 기본이 없습니다.
확장하는 Component는 키 집합을 바꿀 수 없습니다. 축 키를 선언하지 않으므로 기본이 선언한 키를 숨기거나, 제거하거나, 타입을 바꿀 수 없으며, 자체 키를 추가하지도 않습니다. 새 축 키는 그 계약을 소유하는 Component에 속합니다. 기본이 노출하는 것은 무엇이든, 그것을 확장하는 모든 것이 똑같이 노출합니다.
특화는 assertions:를 통해 제약을 강화합니다. 특화가 기본의 축보다 적은 것을 허용해야 할 때(더 좁은 숫자 범위, 상속된 enum:의 부분 집합 등)는 자체 assertions: 블록에 그렇게 명시합니다. 그곳의 규칙이 상속된 스키마가 허용하는 값을 거부합니다. 제약 강화는 바로 이 영역에서 이루어집니다. 아래의 “assertions: 블록”을 참조하십시오.
앞의 두 단락은 하나의 규칙이며, 어느 한쪽만으로는 오해를 낳습니다. 키 집합 축소는 불가능하고, 제약 강화는 가능합니다. 첫 번째만 받아들이면 특화가 아무것도 제약할 수 없다고 결론짓게 되고, 두 번째만 받아들이면 계약을 바꿀 수 있다고 결론짓게 됩니다. 둘 다 아닙니다. 키 집합은 기본이 고정하며, 그 안에서 허용되는 값은 술어로 좁힐 수 있습니다.
어서션 상속은 누적적이며, 누적은 루트부터 이루어집니다. 확장하는 Component의 인스턴스는 Component 자체가 선언한 규칙뿐 아니라 체인이 선언한 모든 규칙에 대해서도 검사되며, 상속된 규칙이 먼저 평가됩니다. 깊이와 관계없이 규칙은 체인 루트에서 아래로 누적되므로, 인스턴스가 둘 이상의 규칙을 위반하면 체인에서 가장 위에 선언된 규칙이 보고됩니다. 가장 근본적인 계약이 먼저 응답하는 것입니다.
상속은 대체가 아니라 추가이므로, 확장하는 Component는 상속된 규칙 이름을 재사용하여 다른 규칙을 선언할 수 없습니다. 이는 extends 체인을 카탈로그에 대해 해석할 때 거부되며, 진단에는 두 Components와 공유된 이름이 표시됩니다. 이 검사에는 기본 Component가 필요하므로 카탈로그를 검증하거나 빌드가 체인을 해석할 때 보고됩니다. 확장하는 문서만 단독으로 검증해서는 발견할 수 없습니다. 규칙 이름은 안정적인 식별자이므로 기본의 규칙을 제거하거나 조용히 이름을 바꾸는 것은 선택지가 아니며, 확장하는 Component에서 이름을 바꾸는 것이 해결책입니다. 상속된 규칙을 같은 이름으로 바이트 단위까지 동일하게 다시 기술하는 것은 아무 효과 없는 작업으로서 허용됩니다.
aggrega pull이 베이스를 가져옵니다. 베이스는 그것을 확장하는 Component에 도달하는 모든 Release의 종속성이며, 다른 무언가가 그것을 지정하는지와는 관계없습니다. aggrega pull은 각 extends:를 체인 끝까지 따라가, 어떤 카탈로그 디렉터리에도 없는 베이스를 레지스트리에서 가져오고, 모든 베이스를 Release의 lockfile에 기록하며, 각 베이스는 그것을 지정하는 Component의 spec.extends에서 참조됩니다. 빌드는 그곳에서 베이스를 읽습니다. 따라서 Manifest는 래퍼 자신의 타입만 매핑하고 그 이상은 하지 않습니다. 베이스에 자체 매핑 줄이 필요한 것은 Aggregate가 베이스의 인스턴스도 선언하는 경우뿐입니다. 전체 카탈로그에 대한 aggrega validate도 같은 방식으로 베이스를 읽으므로, 레지스트리에 게시된 베이스는 pull이 이를 가져올 때까지 그곳에서 aggrega pull을 안내하며 거부됩니다.
스키마 내용 형식은 architecture/13-catalog-and-registry.md §3을 참조하십시오.
예시 A: 기본 Component(기업 기준선) 플랫폼 아키텍트가 기반이 되는 엔터프라이즈 서버를 정의합니다. 이 기본은 필수 운영 클라우드 프리미티브 레이블을 설정하고 스키마에 보안 제약을 정합니다. 축 블록이 변경 없이 상속되므로, 여기의 모든 제약은 작성된 그대로 각 확장 Component에 전달됩니다.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/base-enterprise-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: inject: [env] schema: values: # The corporate baseline constraint. Every Component extending this base # receives this leaf verbatim; none of them can restate or loosen it. tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter # bound expresses it as an assertion, not as a redeclared schema leaf. timeout_ms: { type: integer, default: 5000 } assertions: # A baseline invariant. It is evaluated for instances of this Component AND # for instances of every Component extending it, under this same name. audit-window-is-observable: | {{- if lt (int .values.timeout_ms) 100 -}} {{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}} {{- end -}}예시 B: 확장 Component(기준선 특화)
게이트웨이가 그 기준선으로부터 특화됩니다. 기본의 축을 통째로 가져오고, 자체 구조(레이블, 자체 주입 메커니즘, 부착 슬롯이 있는 토폴로지 소켓)를 추가하며, 어서션으로 상속된 타임아웃을 강화합니다. 기준선의 audit-window-is-observable 규칙은 다시 기술하지 않습니다. 그 규칙은 상속되어 먼저 평가되므로, 이 게이트웨이의 인스턴스는 최소 100, 최대 2000이라는 두 경계를 모두 충족해야 합니다.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/gateway/kong version: 1.0.0 labels: # Every Component declares the reserved base-ontology key, including one # that extends: the envelope requires it on the document itself. component.aggrega.ai/type: "server" api.aggrega.ai/protocol: "http" # merged with the base's labelsspec: extends: core/base-enterprise-server schema: inherited # values, infra and provides are the base's, verbatim inject: [file] # concatenates with the base's [env] -> [env, file] usesSchema: # a socket of its own; the base declared none backend: required: true selector: "component.aggrega.ai/type=stateful-server" inject: [env] featuresSchema: # a slot each connection through it fills credential: sensitive: true inject: [env] description: Password the gateway presents to the configuration backend this connection reaches. assertions: # The tightening. The inherited schema admits any integer for timeout_ms; # this gateway admits only 2000 or less, so the rule rejects a value the # inherited pillar block would accept. timeout-within-gateway-budget: | {{- if gt (int .values.timeout_ms) 2000 -}} {{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}} {{- end -}}이 core/gateway/kong 인터페이스를 실제 Helm 차트에 대해 구현하는 Recipe는 entities/recipe 예시 C(kong-gateway)를 참조하십시오.
assertions: 블록
Component.spec.assertions:는 Component 계약의 아키텍처 불변식을 표현하는 이름 있는 규칙의 선택적 맵입니다. 즉, 어떤 Recipe가 Component에 바인딩되든 개발자의 작성 내용이 충족해야 하는 필드 간 규칙입니다. 각 키는 실패 메시지에 나타나는 규칙 식별자이고, 각 값은 Go 템플릿 본문입니다. 컴파일러는 스키마 검증 후, Recipe 바인딩 전에 인스턴스마다 작성된 순서대로 이를 평가하며, Loud Guardrails 계약에 따라 처음 실패한 규칙이 해당 규칙 자체의 오류 메시지와 함께 빌드를 중단합니다.
spec: assertions: replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt (int .values.secondary.replicaCount) 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}위 규칙은 Component 계약의 속성입니다. 어떤 Recipe가 바인딩되든(Bitnami 차트, 직접 만든 대안, 향후 구현) 복제 모드에는 최소 두 개의 보조 복제본이 필요합니다.
assertions:는 확장하는 Component가 제약을 강화하는 곳입니다. 베이스를 extends:하는 Component는 베이스의 필러 블록을 그대로 상속하고 자체 필러 내용을 선언하지 않습니다. 따라서 상속된 스키마보다 적은 값을 허용해야 하는 특수화는 제한을 좁힌 스키마 리프가 아니라 여기서 술어로, 즉 상속된 필러가 허용하는 값을 거부하는 규칙으로 명시합니다. 예제 쌍과 전체 상속 동작은 위의 “Catalog Authoring: Extending Base Components”에 있습니다. 규칙은 체인을 따라 루트부터 누적되며, 상속된 규칙 이름을 다른 규칙에 재사용하면 이를 대체하도록 허용되지 않고 거부됩니다.
컴파일러는 두 규칙이 동시에 충족될 수 있는지 검사하지 않습니다. 규칙은 템플릿 술어이지 컴파일러가 추론하는 제약이 아니므로, 어떤 값도 동시에 충족할 수 없는 규칙 쌍(최소 100을 요구하는 베이스와 최대 50을 요구하는 특수화)은 카탈로그가 로드될 때 경고를 내지 않습니다. 이는 일반적인 방식으로 드러납니다. 인스턴스가 작성되면 두 규칙 중 먼저 발동하는 쪽에서 빌드가 중단되고, 작성자는 그 규칙의 메시지를 읽게 됩니다. 모순이 미리 보고되리라 기대하지 말고, 특수화의 제약 강화를 베이스가 이미 요구하는 내용과 대조해 확인하십시오.
assertions:는 진정한 필드 간 규칙에 사용하십시오. 필드별 제약(범위, 패턴, enum)은 schema: 키워드에, 필드별 사용자 정의 술어는 간결한 형식의 validate:에, 조건부 형태(하위 트리의 제약이 적용되는지 여부)는 when:에 속합니다. 템플릿 컨텍스트 필드, {{ fail }} 메시지 관례, 평가 단계, Component 및 Recipe 역할에 걸친 예제 등 전체 작성 문법은 templates/assertions-block.md를 참조하십시오.