데이터 분류 체계와 구성
통합 데이터 분류 체계와 구성 규칙
예측 가능한 스키마를 확립하고 인지적 마찰을 없애기 위해, 플랫폼은 보편적으로 이해되는 정확히 다섯 개의 키워드와 엄격한 맵 기반(딕셔너리) YAML 구조를 사용하며, 구조의 루트에는 중첩된 배열 대신 맵을 둡니다.
1. 5-키워드 맵 표준과 완전한 스키마 대칭성
직접적인 구조 어휘: 스키마 설계의 기본 규칙은 루트 데이터 구조가 단일한 구조적 키워드여야 한다는 것입니다. 대화체 영어 구문(depends_on 또는 runs_within 등)을 사용하면 YAML DSL이 개발자에게 더 자연스럽게 읽힐 수 있지만, 이러한 키를 프로그래밍 방식의 Go 템플릿에 매핑할 때 구조적 복잡성이 생깁니다. 직접적인 1:1 변수 매핑을 유지하고 도메인 특화 언어(DSL)의 파편화를 막기 위해, 핵심 카탈로그 엔티티(Component, Feature)의 JSON 스키마는 작성된 인스턴스 슬롯 전반에서 사용되는 동일한 핵심 구조 키워드 집합을 기반으로 거의 완전한 구조적 대칭성을 나타냅니다. 자격 증명 Features(feature.aggrega.ai/kind: secret 레이블이 붙은 것)도 이와 동일한 패러다임을 공유하며, 시크릿을 위한 별도의 스키마는 없습니다.
parameters(전역 환경 계약)- 범위:
Aggregate의 루트에서 정의되며,Release(CI/CD)가parameters:아래에 인라인으로, 또는 외부 파라미터 파일을 가리키는parameters: { $import: <path> }를 통해 채웁니다. - 의미: 환경에 따라 애플리케이션의 인지적 또는 논리적 상태를 동적으로 바꾸는 외부 인수입니다(예:
workers: 2를workers: 10으로 변경). 보간 전에 검증되는 타입이 지정된 계약을 지원합니다(타입 계약 문법 전체는 data-pillars를 참조하십시오). 파라미터 값을 별도 파일에 보관하는 GitOps 워크플로에서는 Release가$import:형식을 사용하며, 컴파일러는 파일 내용을 로드하여 인라인parameters:맵을 대체합니다. 다중 파일 계층화는 Release의extends:체인으로 표현합니다.
- 범위:
values(인지적 의도 - 개발자 소유)- 범위:
Aggregate내의components와 그features첨부 항목 안에서, 자격 증명 Features를 포함하여 일관되게 사용됩니다. - 의미: 핵심 인지 상태, 비즈니스 로직 및 운영 구성입니다. Go 컴파일러에게는 불투명하지만, 카탈로그의 통합
schema:선언(축약형 또는 JSON Schema 2020-12)으로 엄격하게 검증됩니다.
- 범위:
uses(구조적 토폴로지 - 선언적 상태)- 범위:
Aggregate내의components와 그features첨부 항목 안에서, 자격 증명 Features를 포함하여 일관되게 사용됩니다. - 의미: 네트워크 엣지와 의존성을 정의하는 선언적 사실 진술입니다(예: “이 에이전트는 이 데이터베이스를 사용합니다”). Go 컴파일러가 네이티브로 파싱하여 중간 표현(IR) 그래프를 그립니다. 노드 간 타입 안전성을 강제하기 위해 카탈로그의 통합
usesSchema선언으로 검증됩니다.
- 범위:
infra(물리적 현실 - 운영 소유)- 범위:
Release내 바운더리의components와 그features첨부 항목 안에서 일관되게 사용됩니다. - 의미: 지연 바인딩(Late Binding) 중에 주입되는 물리적 점유 공간과 기계적 크기 설정입니다(예:
cpu_limit: "4",port: 5432). Aggregate의 컴포넌트 인스턴스와 그features첨부 항목에는infra필드가 없으며,additionalProperties: false와 결합되어 스키마 검증 시infra를 거부합니다. 카탈로그의 통합schema:선언으로 검증됩니다.
- 범위:
inject(전달 계약 - 명령형 지시)- 범위: 컴포넌트 인스턴스,
uses내의 명시적 대상 정의, 그리고 첨부된features에서, 자격 증명 Features를 포함하여 사용됩니다. - 의미: 전달의 의도를 지시하는 명시적이고 명령형인 지시입니다(예: “컴파일러여, 이 매핑된 값을 환경 변수로 주입하라”). 물리적 출력, 해석된 엔드포인트 또는 조회된 자격 증명에 대한 추상적 계약(
env,file,arg또는 사용자 정의 메커니즘)을 확립하며, 그 마운트가 정확히 어떻게 실행되는지에 대한 물리적 메커니즘은 전적으로 하위 운영 Recipe에 위임됩니다. 각 메커니즘은 항목의 목록([{ in: API_HOST, from: "host" }])이며, 각 항목은in:으로 로컬 식별자를 지정하고from:또는value:중 정확히 하나를 가집니다.
- 범위: 컴포넌트 인스턴스,
.context(범용 메타데이터 파이프)- 범위: 컴파일러가 운영
Recipe템플릿에 암묵적으로 주입합니다. - 의미: 컴파일러가 그래프의 나머지 부분에서 해당 노드를 위해 모은 것(
.context.uses등)을 담아 운영 템플릿 엔진에 직접 전달합니다.
- 범위: 컴파일러가 운영
1:1 매핑의 실제
대화체 전치사를 엄격한 인프라 키워드로 대체함으로써 직접적인 1:1 매핑을 달성합니다. 운영 엔지니어는 문법을 번역할 필요 없이 개발자가 작성한 정확한 키를 참조하기만 하면 됩니다.
구조적 형태: 루트에는 맵, 페이로드에는 배열. 루트 토폴로지 블록(components, features, aggregates, subsystems, boundaries)은 사용자가 작성한 키가 안정적인 인스턴스 ID 역할을 하는 YAML 맵입니다. 이 위치에서는 배열이 유효하지 않으며, 맵 키는 컴파일러가 상호 참조(target: my-db), 그래프 노드 구성 및 Manifest 해석에 사용하는 식별자입니다. 불투명한 페이로드 블록(values, infra, parameters) 안에서는 배열이 완전히 허용되므로, 개발자는 Component의 values 안에 tools_allowed: ["sql", "web"] 또는 hostnames: ["stripe.com", "twilio.com"]를 작성할 수 있습니다. Aggregate 스키마는 이러한 페이로드 블록을 additionalProperties: true로 선언하므로, 이 블록들은 Go 컴파일러에게 불투명하며 전적으로 카탈로그에 내장된 schema: 선언으로 검증됩니다. 이를 통해 프레임워크의 변동성(새로운 AI API 형태, 새로운 클라우드 네이티브 페이로드 형식)은 독립적으로 발전할 수 있는 카탈로그 도메인 안에 두고, Go 컴파일러는 구조적 루트에서 주소 지정 가능한 키만 다룹니다.
2. 정보 흐름: 누가, 언제, 무엇을 위해?
템플릿 네임스페이스 충돌과 물리적 인프라 구성이 인지적 애플리케이션 로직으로 의도치 않게 새어 나가는 것을 막기 위해, 이 아키텍처는 데이터를 여섯 개의 서로 다른 흐름으로 명시적으로 분리합니다.
- 흐름 1: 환경 주입(
parameters): CI/CD 파이프라인이 배포 현실을 주입합니다. 컴파일러는 Release가 제공한 각 값을 타입이 지정된parameters:계약에 대해 검증한 다음, 다운스트림values:스키마 검증을 실행하기 전에 해석된 Go 템플릿 변수를 보간합니다.- 권장 사용법:
parameters는 환경마다 달라지는 인지적 애플리케이션 로직(예:LOG_LEVEL=debug,ENABLE_BETA=true)을 위해 예약되어 있습니다. 운영 사이징과 물리적 인프라 관심사(레플리카, CPU 제한, AWS ARN, 인그레스 호스트 이름)는Release의infra블록과 경계 오버레이를 통해 흐르므로, 개발자의Aggregate는 애플리케이션 의도에 집중할 수 있습니다. - 실용적인 탈출구: 소규모 팀, 빠른 프로토타이핑, 또는 엄격한 분리가 현실적이지 않은 레거시 CI/CD 통합의 경우
parameters로 전역 환경 구성을 스택 전체에 전달할 수 있습니다. 컴파일러는 스키마 검증을 통과하는 것은 무엇이든 받아들입니다. 위의 권장 사항은 사회 계약이며, 컴파일러 규칙이 아닙니다.
- 권장 사용법:
- 흐름 2: 인지적 애플리케이션 의도(Components의
values): 애플리케이션 고유의 로직을 정의합니다. Component의schema:선언(축약형 또는 JSON Schema 2020-12)은 이 페이로드에 대한 엄격한 타입 검사와 검증을 제공하여, 개발자에게 즉각적인 “Shift-Left” 피드백을 주고 요청된 구성이 기반 인프라 API와 일치하도록 보장합니다. - 흐름 3: 운영 Feature 의도(Features의
values): 개발자는 Aggregate에서 동작이 애플리케이션 의도에 해당하는 인프라 기능을 요청하고, 엄격하게 타입이 지정된 자격 증명을 내부 코드를 수정하지 않고 조회합니다. 입력이 모두 운영에 관한 Feature는 개발자values를 갖지 않습니다. 운영 측이 Release에서 해당infra(흐름 4)와 함께 연결합니다. - 흐름 4: 물리적 인프라 사이징(
infra): 개발자를 완전히 우회하여, 물리적infra사이징은 환경별Release에서 로컬 범위의 Components와 그에 연결된 Features(자격 증명 Features 포함)로 직접 명시적으로 투영됩니다. 딕셔너리를 그대로 브로드캐스트하여 생기는 닫힌 스키마 검증 충돌을 피하기 위해,infra사이징은 그것을 대상으로 지정한 명시적 컴포넌트로 엄격하게 국한됩니다. 이로써 컴퓨팅 제한, 레플리카, 기계적 리소스 요구 사항은 운영 도메인에 머무릅니다. - 흐름 5: 계단식 어노테이션(컨텍스트 메타데이터): 광범위한 컨텍스트 데이터(운영 도메인, 네임스페이스, 청구 코드 등)는 계단식 어노테이션으로 처리되어
infra브로드캐스트 오염을 방지합니다. 이들은 출처에 따라 버킷으로 분리되며, 아래에 나오는 각 버킷의 의도된 용도는 사회 계약입니다. Recipe 템플릿은 세 버킷을 모두 읽을 수 있으며, 컴파일러는 이 분리를 강제하지 않습니다(labels-and-annotations 참조)..context.annotations.release(도메인 4 경계): 물리적 현실을 관리하는 데에만 사용됩니다. 운영 측은 Go 템플릿을 통해 이 어노테이션을 엄격한 로컬infra필드로 명시적으로 라우팅합니다(예: 지역 네임스페이스를 컴퓨팅 컴포넌트에 매핑)..context.annotations.aggregate(도메인 1 서브시스템): 인지적·운영 로직을 관리하는 데에만 사용됩니다. 이 어노테이션은 컴포넌트의values페이로드로 명시적으로 라우팅됩니다(예: 팀 청구 코드를 애플리케이션 구성까지 계단식으로 전달)..context.annotations.catalog(도메인 2 카탈로그): 아키텍트가 작성하는 변경 불가능한 고유 특성으로, 주로 프로그래밍 방식의 Wasm 정책 평가에 사용됩니다.
- 흐름 6: 메타데이터 파이프(
.context): 전사적 요구 사항(SOC2 태그)을 물리적 인프라 템플릿에 직접 적용합니다.
3. 네트워크 추상화: “Zero-Port” 관례
- 모범 사례: 개발자는
Aggregate에서 포트를 생략하는 것이 좋습니다. 내부 라우팅은 운영 Recipe가 동적으로 처리합니다. - 탈출구: 애플리케이션의 내부 코드를 변경할 수 없는 경우, 플랫폼 아키텍트가
schema:선언에port필드를 명시적으로 노출합니다. 아키텍처 참고: “Zero-Port” 관례는 플랫폼의 보다 넓은 관심사 분리를 보여 주는 가장 두드러진 예입니다. 물리적 메커니즘을 개발자로부터 추상화한다는 이 동일한 철학은 CPU 요청, 메모리 제한, 운영 도메인, 디스크 사이징에도 적용됩니다. 물리적 인프라 제약이 (레거시 코드나 엄격한 하드웨어 요구 사항 때문에) 개발자의 애플리케이션 페이로드로 반드시 새어 들어가야 하는 경우에는, 항상 아키텍트의schema:선언, 즉 개발자의 페이로드를 검증하는 기준이 되는 선언에 있는 명시적 “탈출구”로 관리해야 합니다.
“Zero-Port”라는 이름은 이 관례를 가리키며, 이 원칙은 레거시 애플리케이션이 하드코딩하는 모든 물리적 인프라 제약으로 일반화됩니다. 아래 스키마는 명확히 인프라 누출 축에 놓이는 예이므로, 애플리케이션이 소켓 계층에서 기대하는 커널/네트워크 타이밍인 tcp_keepalive_seconds를 예시로 사용합니다.
스키마(도메인 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }개발자 YAML(도메인 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versa컴파일러 동작: Go 컴파일러는 tcp_keepalive_seconds: 120을 IR 그래프로 전달합니다. 그런 다음 운영 Recipe가 {{ .values.tcp_keepalive_seconds }}를 읽어 Kubernetes 파드 스펙이나 클라우드 제공자의 로드 밸런서 유휴 타임아웃을 구성함으로써, 스키마를 위반하지 않고 레거시 격차를 메웁니다.
4. 주입 계약과 사전 해석된 맵
다섯 가지 구조적 키워드 가운데 inject는 다른 키워드와 형태가 다릅니다. parameters, values, uses, infra는 선언적 상태로, 개발자가 애플리케이션이 무엇이고 무엇에 의존하는지에 관한 사실을 작성합니다. inject는 명령형 지시로, 개발자가 값이 실행 중인 컨테이너에 어떻게 전달되어야 하는지를 지정하며, 추상적인 데이터 소스(대상의 provides 키, 컴포넌트 자신의 값, 자격 증명 Feature의 볼트 응답)를 구체적인 전달 메커니즘(env, file, arg, 또는 Component가 선언하는 사용자 정의 메커니즘)에 매핑합니다.
이 분리는 구조적입니다. 개발자의 Aggregate는 데이터베이스의 물리적 주소, 시크릿 저장소의 볼트 경로, 클라우드 제공자의 호스트 이름 형식을 명시하지 않고 “데이터베이스 호스트를 환경 변수 DB_HOST로 주입하라”고만 말합니다. 운영 Recipe는 해석된 문자열을 .context.inject를 통해 받아, 조회 체인을 작성하지 않고 그대로 사용합니다.
사전 해석된 맵. 렌더링 중에 컴파일러는 모든 inject 소스(자체 inject 리터럴과 컴포넌트 자신의 provides에 대한 from: 참조, uses[].inject를 통한 컴포넌트 간 참조, FeatureRecipe injectMapping 가로채기)를 .context.inject의 단일 평탄화된 딕셔너리로 해석합니다. 기본 Recipe의 valuesMapping 템플릿이 실행될 때에는 모든 inject 키가 최종 문자열 값을 갖습니다. Recipes는 해석 체인을 따라가지 않고 맵을 직접 순회합니다({{ range $k, $v := .context.inject.env }}).
컴포넌트 자체 값에 대해 개발자가 정하는 이름. Component가 spec.inject를 선언하는 경우, 개발자 자신의 inject: 블록이 컴포넌트 자체의 값과 provides가 전달 파이프에 도달할 때 사용하는 이름을 선택합니다. 컴파일러는 .context.self_inject에서 각 항목의 템플릿이 읽는 하나의 자체 값을 Recipe에 알려 줍니다. 메커니즘별로 각 이름은 provides.<key>에, 정확히 하나의 자체 값만 읽고 그 밖에는 아무것도 읽지 않는 템플릿의 경우 values.<key>에, 그렇지 않으면 빈 문자열에 매핑되며, 이는 연결의 이름이 .context.uses.<alias>.inject에서 취하는 형태와 같습니다. 개발자의 이미지를 실행하는 Recipe에 대한 표준 라이브러리 카탈로그의 관례는, 컴포넌트 자체 값에 대해 원래 선택했을 이름을 기본값으로 취급하고, 어떤 항목도 아직 그 값에 매핑되지 않은 경우에만 자체 값을 기본 이름으로 전달하는 것입니다. 이는 카탈로그의 관례이지 컴파일러 규칙이 아닙니다. 엔터프라이즈 카탈로그는 자신의 컴포넌트 자체 값을 원하는 방식으로 전달할 수 있습니다. 컴파일러는 개발자가 작성한 텍스트에서 맵을 읽으며 이름에 어떤 의미도 부여하지 않습니다.
이중 상태 컨텍스트 의미 체계, 키 충돌 규칙, FeatureRecipe 가로채기 모델, 실제 예제를 포함한 주입 계약의 전체 명세는 topology-triad에 있습니다.
5. 템플릿 엔진(Ops DX)
Platform Ops 엔지니어는 변환 템플릿을 작성하며, 독점 템플릿 언어 없이 표준 인프라 템플릿의 모든 기능을 필요로 합니다. Aggrega의 템플릿은 Go text/template입니다.
- “마법” 문자열 없음: 컴파일러는 Developer가 작성한 맵 키를 그대로 보존합니다. Ops는 표준 Go 맵 인덱싱으로 feature에 안전하게 접근합니다:
{{ (index .features "public-route").infra.hostname }}. - Sprig 라이브러리: 컴파일러는 Helm 표준인 Sprig 라이브러리를 기본으로 등록하므로
| default,| quote,| toYaml같은 파이프라인을 바로 사용할 수 있습니다. - MappingLibrary 프래그먼트: 여러 Recipes가 재사용하는 매핑 프래그먼트는 MappingLibrary에 두고,
$import:로 각 Recipe에 가져옵니다. Helm의 차트 템플릿 헬퍼(include,tpl,required,warn)는 등록되어 있지 않으며, 등록된 것은 sprig-functions에 나열되어 있습니다.
6. 구성 규칙: Aggregates, 서브시스템, Components
- 논리적 그룹화(
subsystems배열): Developer는subsystems를 사용하여 논리적 메타데이터(팀 소유권, 컴플라이언스 레이블)와 횡단 feature를 수십 개의 component에 동시에 적용할 수 있습니다. 서브시스템은 논리/의도 평면에서 재귀적인 폴더 역할을 하며, 물리적 경계를 지정하지 않고annotations를.context.annotations.aggregate버킷으로 하향 전파하고 포함된 모든 component에 feature를 연결합니다. 서브시스템 수준 feature는 Domain 1(Developer Intent)에 속하므로 component 수준 feature와 동일한 스키마(type,values,uses,inject지원)를 따릅니다. 컴파일러는 그래프 확정 시점에 서브시스템 feature를 포함된 각 component의 feature 목록으로 평탄화하며, 실행 순서에서 component 자체 feature 뒤, Release에 연결된 feature 앞에 배치합니다.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- 복합 Aggregates를 지원합니다(모듈 패턴): Aggregates는 Release가 빌드하는 루트 Aggregate이자 재사용 가능한 모듈 역할을 모두 합니다. 부모 Aggregate는 자식 Aggregate를 component와 똑같이 선언하고
parameters를 하위로 전달할 수 있습니다. 강한 결합을 방지하기 위해 자식 Aggregates는exportedComponents:계약을 노출하여 안정적인 공개 인터페이스 이름을 확립합니다. 부모는 이 인터페이스를 통해서만 모듈의 컴포넌트에 도달합니다.uses:대상은 모듈과 그 모듈이 내보낸 별칭 중 하나를 지정하고, 컴파일러는 그 별칭이 가리키는 내부 컴포넌트로 엣지를 연결합니다. 반면 다른 이름으로 모듈 내부에 접근하는 대상은 모듈과 그 모듈이 내보내는 별칭을 명시하며 빌드를 중단합니다. 모듈은 중첩된 모듈의 내보낸 component를 자신의 인터페이스 이름으로 다시 내보낼 수 있으며(선택적으로 이름 변경 가능), 컴파일러는 이러한 재내보내기 체인을 기저의 내부 노드까지 전이적으로 해석하므로, 부모가 대상이 얼마나 깊이 중첩되어 있는지 알 필요 없이 모듈을 임의의 깊이로 구성할 수 있습니다. 어떤 내부 노드로도 해석되지 않는 대상은 여전히 명시적으로 중단되며, 자기 자신으로 되돌아오는 재내보내기 체인은 무한히 따라가지 않고 거부됩니다.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components는 하위 component를 포함할 수 없습니다: Components는 원자적인 빌딩 블록입니다. 구성은 서브시스템과 하위 aggregate를 통해 Aggregate 수준에서 이루어집니다. 애플리케이션에 여러 물리 컨테이너(API + 사이드카 등)가 필요하다면, 그 물리적 중첩은 Component 정의가 아니라 Ops Recipe 템플릿 안에 둡니다.
-
Component당 하나의 일관된 서비스 — 단일 워크로드 경계: Component는 하나의 일관된 서비스를 모델링합니다. 즉 단일 노출 서비스이거나, 한 서비스의 워크로드와 그 서비스의 내부 전용 헬퍼 워크로드를 함께 묶은 것입니다.
component.aggrega.ai/type레이블은 그 한 서비스의 운영 형태를 나타냅니다. 독립적으로 사용 가능한 부분이 없는 하나의 일관된 제품을 이룬다면 단일 Component 안에 여러 물리 워크로드가 있어도 괜찮습니다. 차트가 컨트롤러, 웹훅, 인젝터를 함께 실행하는 서비스도 여전히 하나의 Component입니다. 기준은 다중 워크로드 여부가 아니라 독립적 사용 가능성입니다.경계는 번들에 다른 component가 그 자체로 의미 있게
use할 수 있는 무언가가 포함된 지점에서 그어집니다. 특히 Aggrega가 이미 자체 Component로 모델링하는 데이터베이스, 캐시, 메시지 브로커 같은 외부 인프라가 그렇습니다. 이러한 번들은 하나의 Component가 아니라 하위 aggregate 모듈입니다. 위에서 보인spec.aggregates+exportedComponents패턴으로 서비스마다 하나의 Component를 구성하므로, 각 서비스는 자체 유형, 자체 엣지, 자체 정책 및 스케일링 표면을 가진 주소 지정 가능한 노드가 됩니다.이 휴리스틱을 명확한 규칙으로 표현하면 다음과 같습니다. 차트에 다른 component가 그 자체로 의미 있게 사용할 수 있거나 Aggrega에 이미 Component가 있는 무언가가 포함되어 있습니까? 그렇다면 스택, 즉 서비스별 Components를 구성하는 하위 aggregate 모듈로 모델링합니다. 오직 이 한 서비스만을 위한 것이라면 하나의 Component로 모델링합니다.
여러 서비스로 이루어진 제품 전체를 하나의 불투명한 Component로 감싸는 것은 문서화된 안티패턴입니다. 컴파일러는 주관이 없으며 이를 받아들입니다. 스키마 검증을 통과하는 것은 무엇이든 렌더링합니다. 그러나 표준 라이브러리는 대신 서비스별 Components를 모듈로 구성합니다. 단일체로 감싸면 독립적으로 모델링 가능한 서비스가 토폴로지, 셀렉터, 서비스별 정책 및 스케일링으로부터 가려지기 때문입니다. 이 세분성 원칙은 사회 계약입니다.
../language-reference/vocabulary/social-contracts.md(Component 세분성)를 참조하십시오.
7. 기본 스코프 — 그룹화의 점진적 공개
subsystems(Aggregate 내)와 boundaries(Release 내)는 그룹화 구성 요소이지만, 개발자가 처음부터 이를 선언할 필요는 없습니다. 각 엔터티는 두 가지 작성 형태를 제공하며, 두 형태는 상호 배타적입니다. 이름이 지정된 스코프 아래에 컴포넌트를 그룹화하여 작성하거나, 또는 최상위 수준에 컴포넌트를 직접 작성합니다. 두 가지를 동시에 사용할 수는 없습니다. 최상위 components와 이름이 지정된 스코프를 모두 선언한 문서는 로드 시 엔벨로프 오류로 중단됩니다.
평면(최상위 components) 형태의 경우, 컴파일러는 로드 시 실제 default 스코프를 합성하고 최상위 컴포넌트를 그 안에 접어 넣으므로, 모든 후속 패스는 스코프를 갖춘 균일한 구조를 보게 됩니다. 합성된 스코프는 숨겨진 컨테이너가 아닙니다. IR 안의 실제 노드로서 출처가 표시되며, 개발자가 명시적으로 default라고 이름 붙인 스코프와 구별됩니다. 이 스코프는 작성자가 경로를 읽는 곳에서만 숨겨집니다. 진단과 주소 지정은 개발자가 실제로 작성한 루트 형태의 .spec.components[…]를 표시합니다.
- 평면 Aggregate(최상위 컴포넌트):
subsystems없이spec.components아래에 컴포넌트를 작성합니다. 컴파일러는 로드 시 이를 합성된default서브시스템으로 접어 넣습니다. 서브시스템 스코프 어노테이션과 서브시스템 수준 기능은 선언된 서브시스템에만 적용되며, 평면 형태에는 이러한 것이 없습니다. - 평면 Release(최상위 컴포넌트):
boundaries없이spec.components아래에 컴포넌트를 작성합니다. 컴파일러는 이를 합성된default경계로 접어 넣으며, 그 출력은 평면입니다. 아티팩트는 경계 이름 세그먼트 없이dist/바로 아래(프로바이더별로dist/compose/,dist/helm/, …)에 놓입니다. 이것이 가장 단순한 경우로, 경계에 이름을 붙이지 않고 평면 Compose 또는 단일 클러스터 대상에 대해aggrega build를 실행합니다. (개발자가 선언하고default라고 이름 붙인 경계는 일반적인 이름 있는 경계이며, 자체directory:가 없으면 다른 경계와 마찬가지로dist/boundaries/default/로 출력됩니다.) - 업그레이드 경로: 평면 아키텍처가 그룹화가 필요한 아키텍처(서로 다른 네임스페이스, 별도의 논리적 그룹, 다중 경계 배포)로 성장하면, 개발자는 최상위 컴포넌트를 명시적인
subsystems로 옮기거나 Ops가 명시적인boundaries를 도입합니다. 두 형태는 상호 배타적이므로, 이는 두 형태를 섞는 것이 아니라 평면 형태에서 스코프 형태로 이동하는 것이며, 전환 과정에서 노드 식별성은 유지됩니다.
그 이유는 점진적 공개입니다. 사소한 사용 사례(단일 서비스 데모, 간단한 로컬 프로토타입)에 그룹화를 필수로 요구하면 불필요한 마찰이 생깁니다. “10분 만에 처음부터 동작까지” 온보딩 테스트는 개발자가 서브시스템이나 경계를 먼저 이해하지 않고도 컴포넌트 하나, Manifest 하나, Release 하나로 최소한의 Aggregate를 작성하여 동작하는 출력을 얻을 수 있어야 한다고 요구합니다. 기본 스코프는 진입로이며, 선언된 스코프는 아키텍처가 성장하면서 나아가는 곳입니다.
8. 아키텍처 제약 조건과 권장 패턴
아래 항목은 하나의 권장 패턴과 다섯 가지 제약입니다. 스키마가 강제하는 것은 제약 4와 5입니다. Release에는 values 블록이 없고, Aggregate의 컴포넌트 인스턴스에는 labels 키가 없습니다. 나머지는 컴파일러가 검사하지 않는 관례입니다.
-
권장 패턴: 템플릿 문자열을 통한 파라미터 호이스팅
- 예시: 개발자가
values블록에workers: {{ .parameters.env_workers }}를 작성하며, 값이 선언된 대로 정수로 도착하도록 따옴표 없이 둡니다. - 이유: Aggregate가
env_workers를 타입이 지정된 파라미터(type: integer)로 선언하면, 컴파일러는 먼저 Release가 제공한 값을 계약에 대해 검증합니다. 파라미터 계약 검증은 보간 이전에 이루어지고, 보간은 주변values:스키마 검증 이전에 이루어집니다. 이를 통해 Aggregate의 재사용성이 유지됩니다. Ops는Release의parameters:를 통해 정수를 제공하고, 컴파일러는 이를 타입이 지정된parameters:선언에 대해 검증한 뒤 해석된 값을 문서에 대입하며, Component의schema:선언이 결과 정수를 성공적으로 검증합니다.
- 예시: 개발자가
-
제약 조건 1: 자격 증명은 값이 아니라 첨부입니다
- 권장하지 않는 패턴: 개발자가 컴포넌트에
values: { password: "123" }를 작성합니다. - 이유: 표준 라이브러리의 관례는 자격 증명을
features:아래의 첨부로 요청하는 것입니다. 자격 증명 Featuretype(feature.aggrega.ai/kind: secret레이블이 붙은 것)을 지정하고, 해당 첨부 자체의values를 사용하여 시크릿 저장소에 대한 쿼리를 기술합니다. 이는 컴파일러 검사가 아니라 관례입니다. 컴파일러는values리프가 무엇을 의미하는지 해석하지 않으며 인라인 리터럴을 그대로 전달합니다. 첨부 인터페이스가 있기에 잘 작성된 형태를 타입이 지정된 상태로 사용할 수 있습니다.
- 권장하지 않는 패턴: 개발자가 컴포넌트에
-
제약 조건 2: 기능에 구애받지 않는 Components
- 지원되지 않는 패턴: 아키텍트가 Component의
schema:선언에aws_instance_type: string을 작성합니다. - 이유: Components는 관례상 기능에 구애받지 않습니다. 물리적 하드웨어 대상은 핵심 인지 애플리케이션 로직 안이 아니라 Ops Recipes나 일반
.context어노테이션에 있습니다.
- 지원되지 않는 패턴: 아키텍트가 Component의
-
제약 조건 3: 메타데이터에 대한 조건부 로직
- 지원되지 않는 패턴: Ops가 배포 전략을 근본적으로 바꾸기 위해
Recipe에{{ if eq .context.labels.gpu "true" }}를 작성합니다. - 이유:
.context파이프는 필러별schema:검증을 우회합니다. 검증되지 않은 레이블에 핵심 인프라 로직을 의존하면 플랫폼이 취약해집니다..context객체는 메타데이터 태깅(예: 청구, SOC2)을 전달하며, 구조적 라우팅은 스키마로 검증되는 필러에 속합니다.
- 지원되지 않는 패턴: Ops가 배포 전략을 근본적으로 바꾸기 위해
-
제약 조건 4: Release는 개발자 값을 재정의할 수 없습니다
- 지원되지 않는 패턴: Ops가
Release에서 개발자의 인지 로직을 재정의하려고 시도합니다(예:workers: 4를workers: 10으로 변경). - 이유:
Aggregate는 개발자 의도에 대한 단일 진실 공급원입니다. 값이Aggregate에 하드코딩되어 있으면 모든 환경에서 불변입니다. 값이 환경마다 달라져야 한다면 개발자는 파라미터 호이스팅을 사용합니다.Release스키마는values블록을 금지하여 이를 강제하며, Ops가 할 수 있는 일을parameters계약을 이행하고 물리적infra를 정의하는 것으로 제한합니다.
- 지원되지 않는 패턴: Ops가
-
제약 조건 5: Aggregate의 인스턴스 수준 레이블
- 지원되지 않는 패턴: 개발자가
Aggregate안의 컴포넌트 인스턴스에labels: {}를 작성합니다. - 이유: 레이블은 플랫폼 아키텍트가 작성하는 불변의 카탈로그 수준 특성으로, 정책 엔진과 셀렉터가 읽는 의미적 식별자입니다. Release는 명시적인 맵 기반 ID 지정(
components: { "my-agent": {} })을 통해 컴포넌트를 경계로 라우팅하며, 이를 통해 개발자의 Aggregate에 레이블 작성을 섞지 않고도 컴포넌트별로infra및 기능 재정의를 중첩할 수 있습니다.
- 지원되지 않는 패턴: 개발자가
9. 보안 경계와 명시적 이그레스 가드레일(경계 밖 대상)
어떤 애플리케이션도 진공 속에 존재하지 않습니다. 컴파일된 Aggrega 아키텍처는 엄격하게 매핑된 그래프를 나타냅니다. 그러나 현대 AI 시스템은 이 컴파일된 경계 밖의 엔터티, 예를 들어 공개 SaaS LLM(Anthropic, OpenAI), 일반 공개 API(Stripe, Twilio), 레거시 브라운필드 데이터베이스(온프레미스 Oracle)와 끊임없이 상호작용합니다.
이러한 외부 시스템을 안전하게 통합하기 위해 Aggrega는 보안 경계와 실행 메커니즘을 엄격히 분리합니다. 보안 경계는 범용 Component 규칙과 명시적 이그레스 가드레일이 관장합니다.
1. 범용 Component 규칙
애플리케이션이 로컬 데이터베이스, 관리형 클라우드 리소스, SaaS LLM, 일반 공개 API 엔드포인트 등 어떤 엔터티와 상호작용하든, 그 엔터티는 Aggregate에 별개의 Component로 반드시 선언되어야 합니다. 이 규칙은 관례입니다. 컴파일러는 애플리케이션이 수행하는 호출을 볼 수 없으므로 이를 검사하는 것은 없습니다.
외부 SaaS API와 레거시 데이터베이스를 중간 표현(IR) 그래프의 일급 노드로 취급하면, 개발자는 제로 트러스트 프록시 구성을 아웃바운드 호출에 직접 첨부할 수 있게 됩니다. 예를 들어 Stripe API를 별개의 노드로 모델링하면, 개발자는 여기에 header-injector 기능을 첨부하여, 생성된 구성이 호출하는 에이전트가 원시 API 토큰을 자체 메모리에 보유하지 않도록 보장할 수 있습니다.
2. 명시적 이그레스 가드레일(인프라 적합성)
Aggrega는 네트워크 이그레스를 통제하기 위해 하드코딩된 컴파일러 로직에 의존하지 않고, 경계 보안을 전적으로 기업의 정책 엔진(특정 대상에 구애받지 않는)과 Wasm 렌더링 플러그인에 위임합니다. 이를 통해 생성된 구성이 명시적인 이그레스 승인에 엄격하게 부합하도록 보장합니다.
- 카탈로그 훅(도메인 2): 아키텍트가 공개 SaaS 컴포넌트(예:
core/external-service)를 정의할 때, 여기에 변경 불가능한 기업 레이블(예:security.enterprise.com/zone: "untrusted-external")을 부착합니다. - 정책 가드레일(컴파일 시점): 구성이 생성되기 전에 OPA 또는 Kyverno 정책 엔진이 그래프를 평가합니다. 기업은 다음과 같은 간단한 규칙을 작성합니다: “내부 노드가
untrusted-external레이블이 붙은 노드에 연결되면, 해당 대상 노드의 ID가 환경의parameters.approved_egress배열에 명시적으로 나열되어 있어야 한다.” 개발자가 승인되지 않은 외부 대상으로 데이터를 라우팅하려고 하면 정책 엔진이 빌드를 중단합니다. - 구성 생성(렌더링 시점): 정책을 통과하면 이그레스 규칙은 운영자가 연결한 것으로부터 렌더링됩니다. Release에서 호출하는 컴포넌트에 연결된
core/egress-allowlistFeature는helm에서 그 컴포넌트가 렌더링하는 워크로드마다 KubernetesNetworkPolicy를 하나씩 렌더링하여, 이그레스를 자신의 파드,uses엣지 대상의 파드(해당 파드가 선언한 포트), 클러스터의 DNS, 그리고 공개 SaaS API처럼 클러스터가 실행하지 않는 대상에 대해 연결이 나열한 주소 범위로만 허용합니다. Release가infra.control_plane_present: true로 클러스터의 네트워크 플러그인이 네트워크 정책을 적용한다고 확인하지 않으면 빌드가 중단되며, 주소 범위가 나열되지 않은 그러한 외부 연결이 있으면 그 연결을 명시하며 중단됩니다. 네트워크 정책이 없는compose에서는 이 연결이 빌드를 중단합니다. 개발자는 방화벽 규칙을 작성하지 않습니다.
이는 선언된 토폴로지를 평가하는 거버넌스 판정 역할을 통해, 핵심 Go 컴파일러가 “external”의 의미를 이해할 필요 없이 명시적으로 선언된 인프라가 이그레스 정책에 부합함을 보장합니다. (참고: 진정한 제로 트러스트 이그레스는 런타임에 대상 클러스터가 Default Deny CNI를 실행하는 것에 의존하며, 생성된 구성은 승인된 예외를 매핑할 뿐입니다).
외부 서비스당 하나의 Component
각 외부 서비스는 다중 대상 배열로 합쳐지지 않고 별개의 컴포넌트로 선언됩니다. 애플리케이션이 서로 다른 서드파티 API 다섯 개를 호출한다면, 개발자는 별개의 core/external-service 컴포넌트 다섯 개를 선언합니다. 이러한 서비스별 선언 덕분에 정책 엔진과 Wasm 플러그인이 각 아웃바운드 대상을 개별적으로 지정할 수 있으며, 각 외부 의존성에 서로 다른 이그레스 정책, 서로 다른 프록시 기능, 서로 다른 관측성 훅을 부착할 수 있습니다.
보안과 실행의 분리(“브라운필드” 시나리오)
의미적 레이블(예: untrusted-external)은 실행이 아니라 네트워크 보안 정책을 결정한다는 점에 유의해야 합니다. 이는 Aggrega가 해당 리소스를 프로비저닝하는 아티팩트를 렌더링하는지 여부와 무관합니다.
- 시나리오 A(공개 SaaS API): 카탈로그에서
untrusted-external레이블이 붙습니다(정책 이그레스 가드레일 작동). 참조 워크로드로 실현됩니다(컴퓨트 프로비저닝 없음, §10 참조). - 시나리오 B(내부 레거시 데이터베이스):
internal-trusted레이블이 붙습니다(이그레스 가드레일을 우회하며 VPC 내부에 머무름). 참조 워크로드로 실현됩니다(컴퓨트 프로비저닝 없음, §10 참조). - 시나리오 C(자체 호스팅 데이터베이스):
internal-trusted레이블이 붙습니다. Helm 렌더러 플러그인을 통해 실행됩니다(Kubernetes StatefulSet으로 물리적으로 프로비저닝됨).
10. 빌드가 프로비저닝하지 않는 서비스: 참조 Workloads
애플리케이션이 레거시 온프레미스 데이터베이스나 공개 SaaS API(예: Stripe)와 상호 작용할 때, Universal Component Rule에 따라 이러한 외부 엔터티는 Aggregate에 별개의 컴포넌트로 선언되어야 합니다. 그러나 Aggrega는 이들을 위해 물리적인 Kubernetes Pod나 AWS RDS 인스턴스 아티팩트를 생성하려 해서는 안 됩니다.
그러한 컴포넌트를 실현하는 Recipe는 form: reference인 Workload를 선언합니다. 이는 endpoint(호스트 또는 URL), 선택적으로 port를 가지며 컨테이너는 없습니다. 컴파일러는 둘 다 결정적인 포인터 문자열로 그대로 전달하며 해석하지 않습니다. 참조 Workload에 대해 프로바이더가 무엇을 렌더링하는지는 프로바이더 자신이 정합니다. helm은 엔드포인트의 호스트를 담은 ExternalName Service를 내보내므로, 클러스터 안의 워크로드는 엔드포인트가 DNS 이름인 서비스에 안정적인 클러스터 내부 이름으로 도달할 수 있습니다. compose는 이에 대해 아무것도 렌더링하지 않습니다. Kubernetes는 externalName을 DNS 이름으로 취급하므로, IP 주소로 작성된 엔드포인트에는 Service를 거치지 않고 소비자가 받은 주소로 도달합니다.
두 프로바이더 모두에서 Recipe의 provides:는 프로비저닝되는 컴포넌트의 경우와 똑같이 .context.uses와 inject 계약을 통해 모든 소비자에게 전달됩니다. 따라서 대상이 프로비저닝에서 참조로 바뀌어도 소비자의 연결은 바뀌지 않습니다. 바뀌는 것은 Manifest가 그 대상을 매핑하는 Recipe뿐입니다.
단계별 실행 파이프라인
1. 도메인 1(Aggregate): 개발자 의도 개발자는 레거시 Oracle 데이터베이스를 요청합니다. 그것이 어디에 있는지는 신경 쓰지 않으며, 호출하는 에이전트가 연결 문자열을 환경 변수로 전달받기를 기대한다는 것만 지정합니다. IP는 고정되어 있고 미리 알려져 있으므로 파라미터를 통해 전달합니다.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. 도메인 4(Manifest): 라우팅 Ops는 레거시 데이터베이스 타입을 그 연결 문자열을 포맷하는 Recipe에 매핑합니다. Manifest는 Recipe를 지정할 뿐 그 이상은 하지 않습니다. 지정된 Recipe가 form: reference인 Workload를 선언하며, 이 형식이 노드가 컴퓨트를 프로비저닝하지 않게 합니다. 대상이 무엇이든 맵의 형태는 정확히 하나이므로 라우팅은 완전히 평탄하고 예측 가능하게 유지됩니다.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. 도메인 3(참조 Recipe): 핸드오프 구조화 Ops 엔지니어가 Recipe를 작성합니다. 이 Recipe는 locals 블록에서 개발자의 values로 primary_endpoint 연결 문자열을 만들고, 이를 provides 아래에 게시하며, 데이터베이스의 호스트를 가리키는 참조 Workload를 선언합니다.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. 렌더링 시 컴파일러 실행(핸드오프)
- 컴파일러는
legacy-oracle의 Recipe를 평가합니다.legacy_oracle_ip: "10.0.4.55"를 제공하는 Release에서 그primary_endpoint는oracle://10.0.4.55:1521/PROD_DB입니다. helm에서 참조 Workload는externalName: 10.0.4.55와 포트1521을 가진 ExternalName Servicelegacy-oracle하나를 렌더링합니다.compose에서는 아무것도 렌더링하지 않습니다.- 그다음 컴파일러는
my-agent의 Recipe를 렌더링합니다. 그.context.uses파이프는 Oracle 노드의provides를 전달하며, inject 계약은 이미 그것들에 대해ORACLE_DSN을 해석해 두었습니다.
5. 도메인 3(호출자 Recipe): 계약 이행 Python 워커의 표준 Helm 레시피는 자신이 받은 inject 맵을, 빌드가 프로비저닝하는 데이터베이스의 경우와 똑같이 읽습니다.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. 스키마 브리지 교차 필라 파이핑: 의도와 인프라의 연결
자식 컴포넌트를 통해 특화된 인프라 설정값을 안전하게 노출하는 스키마 브리지 패턴은 inheritance-and-interface를 참조하십시오. 이 패턴은 Component의 schema:에 선언된 개발자용 values: 필드를 Recipe의 valuesMapping: 템플릿이 렌더링된 infra: 형태의 출력으로 전달하는 방식입니다.
12. 그린필드 프로비저닝(“Platform Aggregates”)
플랫폼 엔지니어링에서 반복적으로 빠지는 함정은 라우터(Release 파일)가 무거운 Day-0 클러스터 프로비저닝(예: 앱을 배포하기 전에 새 AWS EKS 클러스터를 구성하는 작업)까지 처리하도록 강제하는 것입니다. 이렇게 하면 길고 읽기 어려운 라우팅 파일이 만들어집니다.
Aggrega는 “끝까지 거북이(Turtles All the Way Down)”라는 원칙으로 이 문제를 다룹니다. Release 스키마에는 인프라를 설치하기 위한 블록이 없으며, 클러스터 프로비저닝은 Platform Aggregates로 모델링됩니다.
AWS EKS 클러스터, Istio 컨트롤 플레인, AWS VPC는 결국 물리적인 클라우드 리소스일 뿐이므로, 애플리케이션 컴포넌트와 정확히 같은 방식으로 모델링됩니다.
- Platform Aggregate: 인프라 팀은 컴포넌트가
core/aws-vpc,core/eks-cluster,core/istio-base인 표준Aggregate.yaml을 작성합니다. - Platform Release: 인프라 팀이 이 aggregate를 배포합니다. 이 플랫폼 컴포넌트들에 바인딩된 렌더러가 기반 인프라를 구성하는 데 필요한 아티팩트를 출력합니다.
- Application Release: 애플리케이션 개발자가 AI 에이전트를 배포할 준비가 되면, Ops 팀은 애플리케이션 자체의
Release파일에 있는 경계로 새로 생성된 클러스터를 지정하기만 하면 됩니다.