Release
Release 엔티티의 개념적 역할(Domain 4 — Aggregate를 Manifest에 바인딩하고 컴포넌트를 물리적 경계에 매핑하는 배포 라우터)은 architecture/04-entity-taxonomy.md에서 다룹니다. 시간적 순서 지정 메커니즘(경계별 syncWave), Dynamic Addressing Polyfill, Parameter Hoisting 패턴은 architecture/12-day-two-lifecycles.md에서 다룹니다. 이 페이지는 Release의 작성 표면을 다룹니다.
Release의 역할
Release는 aggregate를 manifest에 바인딩하고 컴포넌트를 물리적 배포 경계(예: aws-eks-production)에 매핑합니다. Release는 컴파일의 유일한 진입점입니다: aggrega build --release release.yaml.
Release는 물리적 현실을 엄격하게 parameters 블록에만 주입하여 추상적인 aggregate 계약을 이행하며, 물리적 사이징(CPU나 포트 등)은 infra 병렬 네임스페이스를 통해 주입합니다.
모든 Release는 자신의 Manifest를 지정하는 manifest: 필드를 선언합니다(Release가 extends:를 사용하여 부모의 manifest 포인터를 상속하는 경우는 예외입니다). aggrega build CLI는 이 필드를 직접 읽습니다. --manifest CLI 플래그는 존재하지 않으므로 의존성 명세는 Release 자체와 함께 Git에 커밋된 상태로 유지되며, 배포 이력은 Release 자체의 Git 이력을 통해 감사할 수 있습니다.
aggregate: 및 manifest: 필드는 언어의 나머지 부분이 참조를 해석하는 방식과 동일하게 식별자 또는 상대 경로 파일로 해석되며, release 기준의 파일명 어간으로는 절대 해석되지 않습니다. ./ 또는 ../ 값은 명시적인 로컬 파일이며, Release를 기준으로 한 상대 경로에서 직접 읽힙니다. 접두사 없는 토큰은 식별자, 즉 참조된 엔티티의 metadata.name입니다. manifest: 식별자는 Release 자신의 디렉터리를 스캔하여 해석됩니다(Manifest는 배포 측 운영자 구성이므로 catalog나 registry 계층이 없습니다). aggregate: 식별자는 전체 캐스케이드, 즉 Release의 디렉터리, 그다음 catalog, 그다음 registry를 거쳐 해석됩니다. 따라서 Release는 게시된 Aggregate를 식별자로 지정할 수 있으며, 동일한 게시 모듈은 Release의 최상위 spec.aggregate이든 다른 Aggregate 내부의 하위 aggregate이든 똑같이 해석됩니다. 이 식별자-또는-경로 모델 덕분에 공유 Aggregate 하나가 참조를 파일명에 결합하지 않고도 여러 Release 변형을 뒷받침할 수 있고, 게시된 Aggregate를 이름으로 직접 배포할 수 있습니다.
경로는 워크스페이스 안에 머뭅니다. ./ 또는 ../ 값은 워크스페이스가 보유한 파일을 지정하며, Release가 작성하는 다른 모든 경로, 즉 아래에서 설명하는 extends:와 parameters의 $import:도 마찬가지입니다. 작성된 그대로 워크스페이스 밖으로 올라가거나, 경로상의 심볼릭 링크가 워크스페이스 밖으로 이끄는 경로는 그것이 지정하는 파일에서 아무것도 읽기 전에 거부됩니다. 워크스페이스 밖에 보관된 Aggregate를 배포하려면 식별자로 지정하고, 그것을 보유한 디렉터리를 워크스페이스 구성에서 catalog 디렉터리로 나열하십시오. Manifest, extends:가 지정하는 Release, parameters 파일은 Release 옆에서 읽히며 이름으로 조회되지 않으므로 워크스페이스 안에 보관합니다. 명령줄에서 지정하거나 워크스페이스 구성이 지정하는 Release가 워크스페이스 밖에 있으면 그 자체가 하나의 루트가 됩니다. 그 Release가 작성하는 모든 경로와 그 extends: 체인이 이끄는 Release가 작성하는 모든 경로는 해당 Release를 보유한 디렉터리 안의 파일로 이어져야 하며, 그 디렉터리 밖으로 올라가거나 링크가 밖으로 이끄는 경로는 같은 방식으로 거부됩니다. 이러한 Release가 지정하는 것은 그 옆에 두거나, 둘 다를 보유한 워크스페이스에서 빌드하십시오. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (다른 파일에 대한 참조가 머물러야 하는 디렉터리 밖으로 이어짐)“를 참조하십시오.
Release는 컴파일된 아티팩트의 목적지를 지정합니다. provider 디스패치는 Release가 가리키는 Manifest에 속합니다(역할 분담은 Manifest vs. Release: 관심사 분리를 참조하십시오).
환경 메타데이터
모든 Release 메타데이터 블록은 environment: 필드를 받습니다. 이 필드는 Release가 배포되는 환경을 식별하는 자유 형식 문자열입니다(일반적인 값: production, staging, dev). 이 필드는 정보 제공용입니다. 열거형도, 스키마 수준 패턴도 없으며 type: string 외에는 엔터티 간 검증도 없습니다. 컴파일러는 helm 프로바이더가 렌더링하는 모든 Kubernetes 매니페스트에 나머지 Aggrega 출처 레이블 모음과 함께 이 값을 aggrega.ai/environment 레이블로 내보냅니다. 값이 유효한 Kubernetes 레이블 값이면 작성된 그대로 내보내고, 그렇지 않으면 유효한 값으로 다시 쓰며 정확한 값은 aggrega.ai/environment 어노테이션으로 전달합니다(따라서 eu/prod에는 eu-prod 레이블이 붙습니다). helm-chart 프로바이더는 하위 차트에 배치하는 $import:로 로드된 각 아티팩트에 같은 레이블을 추가하며, 하위 차트 자체의 템플릿은 작성자가 쓴 내용을 그대로 유지합니다. compose 프로바이더는 자신이 내보내는 각 서비스에 같은 값을 aggrega.ai/environment 레이블로 붙입니다.
environment: 작성은 다섯 가지 실무 패턴에 따라 이루어집니다.
-
OTel/FinOps 비용 귀속. 클라우드 비용 대시보드(AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth)는 환경별로 Kubernetes 파드를 태그 필터링합니다.
aggrega.ai/environment: production레이블은 Helm provider의 레이블 주입을 통해 파드 레이블로 전달되며, 비용 보고서는 리소스별 수동 태깅 없이aggrega.ai/environment기준으로 지출을 그룹화합니다. -
OTel 트레이스 및 로그 필터링. 관측성 대시보드(Datadog, New Relic, Honeycomb, Grafana Tempo)는 환경 레이블로 텔레메트리를 필터링합니다.
aggrega.ai/environment: staging을 사용하면 운영자는 네임스페이스 관례나 차트 이름으로 필터링하지 않고도 로그 쿼리와 트레이스 조회 범위를 staging으로 한정할 수 있습니다. 렌더링된 전체 영역에 걸친 단일 표준 레이블입니다. -
Kubernetes 오퍼레이터 대상 지정. GitOps 컨트롤러(ArgoCD, Flux)와 정책 오퍼레이터(Kyverno, OPA Gatekeeper)는 환경별 정책을 위해 환경 레이블로 리소스를 필터링하기도 합니다(예: “production 전용 리소스에는 approved-image-source 레이블이 필요하다”).
aggrega.ai/environment레이블은 네임스페이스 관례나 명명 패턴과 구별되는 안정적인 셀렉터를 제공합니다. -
다중 리전 프로덕션 구분.
production-us-eastRelease와production-eu-westRelease를 함께 운영하며 둘 다metadata.environment: production인 팀은 리전 전반에서 동일한aggrega.ai/environment: production레이블을 얻습니다. 별도의 리전 레이블과 결합하면 리전 간 비용 집계(“전체 프로덕션 지출”)와 리전별 세부 분석이 가능합니다. -
컴플라이언스 범위 지정. SOC 2, PCI, HIPAA 증거 수집은 환경별로 범위를 정합니다(프로덕션 전용 감사 등).
aggrega.ai/environment레이블은 컴플라이언스 증거 수집 도구(Vanta, Drata)가 감사 범위별로 리소스를 필터링하는 데 사용됩니다.
스키마는 모든 Release에 environment:를 요구합니다. 이 값은 정보 제공용이며, 컴파일러는 aggrega.ai/environment 레이블을 쓰기 위해서만 이 값을 읽습니다.
스키마 수준 제약 조건
두 가지 구조적 보장이 Aggregate를 단일 진실 공급원(Single Source of Truth)으로 보호합니다.
values:는 금지됩니다. Aggregate를 단일 진실 공급원(Single Source of Truth)으로 보호하기 위해 Release 스키마는values:블록을 기계적으로 금지합니다. Operator는 Release에서 어떤 Component나 Feature에도values를 선언할 수 없습니다. 이 금지는uses엣지에도 적용됩니다. Release의 엣지별uses항목은infra와 연결에 작성하는 attachment를 담으며, 이 attachment도infra를 담습니다.values는 절대 담지 않습니다(개발자 대상 엣지별 값과 연결에 있는 attachment의 값은 Aggregate에 남습니다). 개발자 대상 값의 환경별 변형은 Parameter Hoisting을 통해 흐릅니다. Developer가 Aggregate에 타입이 지정된parameters.*필드를 노출하고, Component의values템플릿이 이를 참조하며, Release가 해당 환경에 맞게 파라미터를 채웁니다. 스키마 수준 금지를 명시적으로 설명하는 내용은 architecture/06-data-taxonomy-and-composition.md §8 제약 조건 4를 참조하십시오. Release의uses엣지 표면, 즉 무엇을 구성하고 연결할 수 있는지는 아래의 엣지별 연결 구성에 설명되어 있습니다.extends+aggregate:는 거부됩니다. 추적할 수 없는 “aggregate 변경” Releases를 방지하기 위해, Release가extends를 사용할 때aggregate포인터를 선언하면 Release 스키마가 이를 거부합니다. 자식 release는 부모와 정확히 동일한 Developer Intent에 매핑되어야 합니다. 그러나manifest는 선택 사항이 되어 “Late Binding”을 가능하게 합니다. 즉, Operator가 전체 물리적 토폴로지를 상속하면서 Manifest만 정밀하게 교체할 수 있습니다.
parameters: 블록
Release는 Aggregate가 선언하는 타입이 지정된 매개변수 계약을 이행합니다. spec.parameters:는 작성 표면으로, 키는 Aggregate의 parameters.* 선언과 일치하고 값은 환경별 이행 값을 제공하는 YAML 맵입니다.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: parameters: db_size: { type: string, required: true } timeout_seconds: { type: integer, default: 30 } region: { type: string, enum: [us-east-1, eu-west-1], required: true }# Release fulfills the contract for this environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"각 값은 매개변수 계약 계층에서 Aggregate가 선언한 스키마 검사를 거치며, Release가 필수 매개변수를 생략하거나(E0165, parameter-missing) 슬롯의 계약이 거부하는 값을 제공하면(E0164, parameter-contract-violation) 빌드가 중단됩니다. default:와 함께 선언된 매개변수는 Release가 해당 슬롯을 생략할 때 기본값을 받습니다. 타입이 지정된 계약이 유일한 작성 어휘입니다.
두 가지 작성 모드 — 내용 형태에 따른 분기. parameters:는 인라인 YAML 맵(모드 1, 위 예시) 또는 로컬 파일을 가리키는 단일 $import: 키(모드 2) 중 하나를 받습니다:
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yaml상대 $import: 경로는 명령을 어디에서 실행하든 해당 경로를 작성한 Release가 있는 디렉터리를 기준으로 해석되므로, 명령줄과 편집기는 같은 파일을 읽습니다. 절대 경로는 그 자체로 위치를 지정하며, 어느 쪽이든 워크스페이스 내부의 파일을 가리켜야 합니다. 워크스페이스 외부에서 지정된 Release의 경우에는 그 Release가 있는 디렉터리 내부의 파일이어야 합니다. 이 위치에서 두 모드는 상호 배타적이며, 하나의 파일만 가져올 수 있습니다. 여러 파일에 걸친 매개변수 계층화는 Release extends: 체인의 영역입니다. 부모 Release가 기본 매개변수 집합을 제공하고, 자식이 환경별로 이를 확장하고 재정의합니다. 이 패턴은 아래의 Composite Release / extends: 상속을 참조하십시오.
parameters와 infra의 경계. 매개변수는 Aggregate가 선언하는 타입이 지정된 슬롯으로 표현된 Developer의 인지적 의도를 담으며, Release가 이를 이행합니다. Release의 infra:는 특정 컴포넌트나 Feature 부착에 연결된 Operator의 물리적 사이징(레플리카 수, CPU/메모리 한도, 스토리지 클래스)을 담습니다. 매개변수는 .parameters.X를 통해 Aggregate의 values: 템플릿으로 흐르고, infra:는 .infra.X를 통해 Recipe의 valuesMapping: 템플릿으로 흐릅니다. 데이터 기둥 분류 체계는 architecture/06-data-taxonomy-and-composition.md §3을, 파이프라인 전반의 매개변수 수명 주기는 templates/parameters-context.md를 참조하십시오.
경계와 기본 범위
Release는 구성 요소를 **경계(boundary)**로 묶습니다. 경계는 물리적 배포 단위이며, 각 경계는 고유한 출력 디렉터리와 어노테이션 캐스케이드를 가집니다. 단일 경계가 일반적인 경우이므로 별도의 절차가 필요하지 않습니다.
단일 범위(기본값). 구성 요소를 spec.components: 아래에 직접 작성하고 boundaries: 블록은 생략합니다. 컴파일러는 이들을 합성된 default 경계로 접어 넣으며, 이 경계의 출력은 **평탄(flat)**합니다. 아티팩트는 dist/ 바로 아래에 놓이며(아래에서 설명하는 안전한 subDirectory 기본값에 따라 provider별로 dist/compose/, dist/helm/, …), 경로에 경계 이름 세그먼트가 없습니다. 이것이 가장 단순한 배포입니다. 경계에 이름을 붙이지 않고 평탄한 Compose 또는 단일 클러스터 대상에 대해 aggrega build를 실행합니다.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080다중 범위. Release가 둘 이상의 물리적 그룹(별도의 클러스터, 리전 또는 sync wave)에 걸치는 경우, boundaries: 아래에 이름 있는 경계를 선언합니다. 각 경계는 고유한 directory:, 어노테이션 캐스케이드, syncWave:를 가지며, 구성 요소는 해당 경계 안에서 지정됩니다.
상호 배타성. spec.components:와 spec.boundaries:는 Release 루트에서 상호 배타적입니다. Release는 둘 중 하나만 작성하며, 둘 다 작성할 수는 없습니다. 둘 다 선언한 문서는 로드 시 엔벌로프 오류와 함께 중단됩니다. 최상위 components 표면은 경계의 components와 동일한 구성 요소별 운영자 형태(infra:, annotations:, uses:)를 가집니다.
이름이 default인 선언된 경계. 평탄한 출력은 이름이 아니라 합성된 기본 경계의 속성입니다. boundaries: 아래에 이름이 default인 경계를 명시적으로 선언한 Release에서 그 경계는 일반적인 이름 있는 경계입니다. 그 출력은 다른 선언된 경계와 똑같이 해당 경계의 directory:(기본값 dist/boundaries/default/)를 따릅니다.
기본 범위 패턴은 architecture/06-data-taxonomy-and-composition.md §7을 참조하십시오.
공간 분리와 출력 경로
각 boundary는 컴파일된 아티팩트를 위한 물리적 출력 directory를 선언하며, boundary 안의 component는 component별 subDirectory로 이를 재정의할 수 있습니다. 컴파일러는 둘을 결합하여 최종 아티팩트 경로를 계산하며, 모든 플랫폼에서 슬래시로 구분된 형식을 사용합니다: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- 하나의 디렉터리, 하나의 표기. 평가된 경로는 한 번 정리되므로
out/a,out//a,./out/a,out/a/는 하나의 디렉터리입니다. 경로가 정리 후 같은 디렉터리가 되고 같은 provider를 통해 렌더링되는 boundary들은, 동일한 경로로 작성된 boundary들과 똑같이 함께 조립됩니다. - 경로는 출력 루트 아래에 머뭅니다. 출력 루트 밖으로 올라가는 경로(
..,../escape,a/../..), 절대 경로, 또는 디렉터리를 전혀 지정하지 않는 경로(비어 있거나 정리 결과가 출력 루트 자체인 경로)는 무엇이든 기록되기 전에 빌드를 중단합니다. 메시지에는 Release, boundary, 문제가 된 필드(directory:또는subDirectory:), 그리고 평가된 값이 표시됩니다. 그 값은 템플릿의 결과인 경우가 많기 때문입니다. - 안전한 기본값.
subDirectory를 생략하거나 비워 두면 컴파일러가 자동으로subDirectory: "{{ .capability }}"를 적용합니다. 각 렌더링 capability의 아티팩트(Helm, Helm-chart, Compose, Terraform, CloudFormation)는 각자의 하위 폴더에 놓이므로, 다운스트림 CI/CD 도구에서 아티팩트가 섞여 충돌하는 일을 방지합니다. 명시적으로 작성한subDirectory: ""는 생략한 것과 똑같이 읽히므로 이 기본값도 그대로 적용됩니다. - 평면 재정의. 하위 디렉터리를 완전히 비활성화하려면(모든 아티팩트를
directory바로 아래에 두려면)subDirectory: "."를 설정합니다. 빈 문자열로 평가되는subDirectory템플릿(예:sub가""로 설정된"{{ .parameters.sub }}")도 마찬가지로 하위 디렉터리를 비활성화합니다. - 템플릿 변수.
directory는{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}, 그리고 상위 boundary에서 이어지는 데이터를 위한{{ .parent_boundary.* }}로 평가됩니다.subDirectory는 같은 집합에{{ .component_id }}(component별 재정의에만 해당)를 더해 평가됩니다. 컴파일러는 경로 템플릿을missingkey=error로 평가하므로, 선언되지 않은 변수를 참조하면 정확한 진단과 함께 빌드가 중단됩니다. 컨텍스트별 매트릭스와 상위 boundary 전파 규칙은 경로 템플릿 변수를 참조하십시오.
boundary 어노테이션은 포함된 모든 component로 아래쪽으로 전파되며, infra는 그것을 대상으로 하는 component에만 엄격하게 국한됩니다. 재귀적인 boundaries 맵은 임의의 중첩(boundary 안의 boundary 안의 boundary)을 허용하며, 어노테이션 전파와 로컬 infra 불변 조건은 모든 수준에서 유지됩니다.
예제:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" # Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`. annotations: "aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations components: api-server: infra: { replicas: 5 } # Strictly local aws-rds: # Scenario B: Bespoke Enterprise Naming. subDirectory: provisioning postgres-db: # Scenario C: The Flat Directory Override. subDirectory: "." # not "", which takes the default이 메커니즘으로 전파된 어노테이션은 다운스트림 Recipe 템플릿에서 .context.annotations.release를 통해 나타납니다. 렌더러가 이를 사용하는 방식은 Recipe 작성과 템플릿 확장 매트릭스를 참조하십시오.
구조화된 어노테이션 값. Manifest 바인딩이 하나의 어노테이션 키에 대해 여러 infra 기둥 라우팅 경로를 선언하면, Release 측 어노테이션 값은 하나의 선언에서 여러 Feature 스키마 필드의 값을 담는 구조화된 객체가 될 수 있습니다:
boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100 components: api: annotations: feature.myco/db-pool: max_connections: 200 # closer-level override # pool_size not listed → inherits 20 from boundary구조화된 값은 하위 키별 깊은 병합으로 전파되며, 더 가까운 수준의 하위 키가 상위 하위 키를 재정의합니다. 하위 키별 null은 형제 하위 키를 유지한 채 해당 하위 키 하나만 제외합니다. Release 측은 바인딩 맵의 기둥이 infra인 하위 키만 적용하며, values로 라우팅되는 하위 키는 Aggregate 측 어노테이션에 속합니다. 양측 조합, 하위 키별 타입 검증, 완화된 기본값 원칙 등 구조화된 값에 대한 전체 설명은 providers/well-known-annotations.md §“Structured annotation values”를 참조하십시오.
잘 알려진 어노테이션. 임의의 키 외에도 Aggrega 표준 라이브러리는 aggrega.ai/ 및 feature.aggrega.ai/ 네임스페이스 아래에 배치, 네트워킹, 보안, 관측성 범주로 묶인 잘 알려진 어노테이션 집합을 정의합니다. Release boundary에 어노테이션을 추가하는 작성자는 전체 매트릭스와 provider별 사용 규칙을 providers/well-known-annotations.md에서 확인해야 합니다. 이 페이지는 어떤 provider가 각 잘 알려진 키를 적용하는지, 그리고 키가 있을 때 어떤 동작을 내보내는지 설명합니다.
엣지별 연결 구성
boundary의 component는 Component의 카탈로그 usesSchema가 선언하는 소켓 안에서 토폴로지 엣지를 구성하거나 연결하는 uses: 블록을 가질 수 있습니다. 이것은 운영자의 연결별 표면이며, 개발자가 작성한 아키텍처의 소유권을 개발자가 유지하도록 범위가 제한되어 있습니다.
- 기존 엣지 구성. 개발자가 이미 선언한 엣지에 엣지별
infra를 설정합니다. 항목은 개발자의 별칭을 지정하고infra를 제공합니다. 항목은 개발자가 연결한 것과 같은 대상을 지정하거나 대상을 생략합니다.infra는 소켓의infraSchema에 대해 검증됩니다. - 바인딩되지 않은 소켓 연결. Component의
usesSchema가 선언하지만 개발자가 연결하지 않은 소켓으로, 기존 component를 가리키는 엣지를 생성합니다. 생성된 엣지도 엣지별infra를 가질 수 있습니다. - 연결에 첨부. 항목의
features:아래에 첨부를 두며, 키는 소켓이featuresSchema에 선언한 슬롯, 즉 개발자의 연결 항목이 채우는 것과 같은 슬롯입니다. 각 첨부는type, 선택적description,infra를 가지며values는 절대 가지지 않습니다. 개발자가 같은 연결에서 이미 채운 슬롯 아래에서는 항목이 그 첨부의 크기를 정합니다. type과 values는 Aggregate에서 오므로infra만 작성합니다(여기에 작성한type은 Aggregate의 것과 일치해야 하며, 그렇지 않으면 빌드가 이 항목에서 둘 다를 명시하며 중단됩니다). 개발자가 비워 둔 슬롯 아래에서는 첨부가 Release 자신의 것이며type이 필수입니다. 어느 경우든 채움은 슬롯의selector를 따라야 하며, 개발자의 것과 똑같이required슬롯에 포함되어 계산됩니다.
이 표면은 **생성은 가능하되 대상 변경은 불가(create-not-retarget)**입니다. Release는 바인딩되지 않은 소켓으로 엣지를 추가할 수 있지만, 개발자가 이미 선언한 엣지의 방향을 바꿀 수는 없습니다. 개발자의 엣지와 다른 대상을 지정하는 엣지별 항목은 빌드를 중단시키고, 같은 대상을 지정하는(또는 생략하는) 항목은 그 엣지를 구성합니다. 또한 Release는 엣지나 그곳에 작성하는 첨부에 values를 선언할 수 없고(개발자 대상 values는 Aggregate에 남습니다), usesSchema가 선언하지 않은 소켓을 바인딩할 수 없으며, 존재하지 않는 component를 엣지로 가리킬 수 없습니다. 각각은 치명적 중단입니다. 모든 엣지가 그려진 뒤에 존재하지 않는 연결에 infra 또는 features를 설정하는 항목도 마찬가지이며, 소비하는 component가 active: false로 꺼져 있는 경우는 예외입니다. errors/fatal-halts.md §“When building the topology”를 참조하십시오.
연결의 첨부를 해당 연결에 유지하는 중단이 세 가지 더 있습니다.
- 소켓이 슬롯을 선언하지 않은 이름은 Aggregate의 연결 항목에서와 똑같이, Release의 이 항목에서 중단되며, 소켓이 선언하는 슬롯과 그중 이름에서 한 번의 편집 거리에 있는 슬롯을 명시합니다.
- Release만 만드는 첨부를
type없이 작성하면 연결 항목에서 슬롯을 명시하며 중단됩니다. Release가 만드는 첨부는values를 가지지 않으므로,values에 아무것도 요구하지 않는 Feature에 적합합니다. 스키마가 값을 요구하는 Feature는 같은 항목에서 누락된 값으로 중단됩니다. 호출자의 로케이터를 가지는 표준 라이브러리의 자격 증명 Features는values에 아무것도 요구하지 않습니다. 각각은 로케이터를infra에서도 받습니다(아래 참조). - 합성된 이름을 연결 이외의 곳에 작성하면 중단됩니다. 연결 첨부는
<alias>.<slot>이라는 이름으로 소비하는 component의 첨부가 되며(Aggregate의 연결 항목 참조), component 항목 자체의features:키와 boundary의 키는 모두 점을 허용합니다. component 항목이 그 이름을 작성하거나, boundary가 그 이름을 작성하여 해당 연결이 그것을 가지는 component — 그 boundary나 그 안에 중첩된 boundary에 배치된 component, 라우팅된 하위 모듈의 component 포함 — 에 도달하면, 도달한 component마다 한 번씩 두 표기를 모두 명시하며 중단됩니다. 소켓의 슬롯은 각 연결에서 채워지며, 더 넓은 범위에서 캐스케이드되는 첨부로는 절대 채워지지 않습니다.
spec: components: router: uses: models: # Size the attachment the Aggregate declared on the "gpt" connection: infra only. gpt: features: credential: infra: { rotation: hourly } # Attach on a connection the developer left without one: the type is required. plain: features: credential: type: core/generated-secretRelease가 연결하는 연결의 자격 증명은 시크릿을 infra에서 지정합니다. Release가 연결하는 연결에는 Aggregate에 항목이 없으므로 그곳에서 자격 증명의 values를 작성하는 것이 없고, Release는 어디에도 values를 작성하지 않습니다. 따라서 호출자의 로케이터를 가지는 각 표준 라이브러리 자격 증명 Feature — core/referenced-secret, core/referenced-secret-set, core/secret-value, core/secret-provided — 는 로케이터를 values뿐 아니라 infra에서도 받습니다. 즉 origin, 또는 core/referenced-secret-set의 경우 entries를 두 pillar 모두에서 같은 형태와 같은 sensitive: true 선언으로 받습니다. 모든 실현은 로케이터를 가진 pillar를 읽습니다.
spec: components: router: uses: models: gpt: target: gpt # wire the socket the developer left unbound features: credential: type: core/referenced-secret infra: origin: openai-team-a # the secret the operator names로케이터는 첨부마다 정확히 하나의 pillar에 작성됩니다. 같은 슬롯에 대해 Aggregate의 values와 Release의 infra 양쪽에 로케이터를 가지거나 어느 쪽에도 가지지 않는 첨부는 Feature 자체의 어서션(E0033)에서 중단되며, Feature, 첨부, component를 명시하고 둘 중 어느 경우였는지 알려 줍니다. 이 규칙은 컴파일러가 아니라 해당 Features의 카탈로그 엔터티에 속하며, 컴파일러는 다른 Feature의 어서션과 마찬가지로 그 어서션을 평가합니다. 로케이터 이외의 필드는 원래 pillar를 유지합니다. key는 values 리프로 남으므로, Release만 만드는 첨부는 Feature의 기본 데이터 키인 value를 읽습니다. values: 금지는 변하지 않습니다. 운영자의 로케이터는 infra입니다.
core/secret-provided는 연결에 맞지 않는 유일한 것입니다. 이 Feature는 첨부 자체의 inject: 블록이 전달하도록 값을 게시하는데, 연결의 첨부는 어느 문서에서도 inject: 블록을 가지지 않으므로 연결에서는 어떤 inject: 블록도 그 값을 전달하지 않습니다. 그곳에서는 core/referenced-secret 또는 core/secret-value를 사용하십시오.
spec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: components: api-server: uses: databases: # Configure the developer-declared edge "primary": add per-edge infra. # The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget. primary: infra: { storage_class: fast-ssd } caches: # Wire an edge into the declared-but-unbound "caches" socket to an existing component. main: target: redis-prod infra: { storage_class: standard }확정된 엣지별 infra는 소비하는 component의 렌더 컨텍스트의 .context.uses.<alias>.infra.<key>로 흘러갑니다. 대상 component의 컨텍스트에는 절대 나타나지 않으므로, 대상의 렌더링 결과는 그곳으로 엣지를 구성하는 소비자와 무관하게 불변입니다. 연결의 첨부도 소비하는 component에 그 첨부 중 하나로 놓입니다. 그 infra는 같은 슬롯에 대한 Aggregate의 values와 병합되고, 그 FeatureRecipe는 둘 모두를 대상으로 렌더링합니다. 소비하는 component의 Recipe는 연결 아래의 .context.uses.<alias>.features.<slot>에서 이를 읽고, 그 Workload는 슬롯 옆에 연결을 지정하여 이를 전달합니다. 연결이 가지는 자격 증명 전달을 참조하십시오.
aggregates: 필드 — 중첩된 하위 모듈을 경계로 라우팅하기
Aggregate가 spec.aggregates:를 통해 중첩된 하위 모듈을 선언하면, Release는 대상 경계 안에 components:와 나란히 aggregates:를 선언하여 각 하위 모듈의 컴포넌트가 어느 경계에 배치될지 결정합니다.
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: aggregates: finance: type: finance-module:1.2.0 analytics: type: analytics-module:2.0.0 components: gateway: type: core/ingress---# Release routes each sub-aggregate into a specific boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Aggregate.spec.aggregates: 아래에 나열된 모든 하위 aggregate를 정확히 하나의 경계에 배치합니다.
라우팅은 컴포넌트를 배치합니다. 라우팅된 하위 모듈의 모든 컴포넌트는 그 모듈을 라우팅하는 경계에 배치되며 해당 경계의 directory, subDirectory, syncWave 및 어노테이션 캐스케이드를 받습니다. 이는 components: 아래에 직접 이름이 지정된 컴포넌트가 받는 것과 동일한 컨텍스트이며, 생성된 아티팩트에 찍히는 aggrega.ai/boundary-path 출처 정보도 포함합니다. 따라서 하위 모듈을 라우팅하는 것과 그 각 컴포넌트를 빈 본문과 함께 정규화된 점 경로로 지정하는 것은 동일한 아티팩트를 생성합니다. 라우팅은 이를 더 짧게 표현하는 방법이며, 하위 모듈의 내용을 알지 못한 채 표현할 수 있는 유일한 방법입니다.
컴포넌트는 정확히 하나의 경계에 속하며, 문서가 컴포넌트를 두 번 배치하면 빌드가 중단됩니다. 같은 하위 모듈이 두 경계로 라우팅된 경우, 하위 모듈이 한 경계로 라우팅되면서 그 컴포넌트 중 하나가 다른 경계에 지정된 경우, 또는 컴포넌트가 직접 지정되는 동시에 라우팅 항목을 통해서도 지정된 경우가 이에 해당합니다. 어느 쪽을 유지할지는 작성자가 결정할 일이므로 진단은 두 위치를 모두 표시합니다. 하위 모듈을 어떤 경계로 라우팅하고 그 컴포넌트 중 하나를 같은 경계 아래에 지정하는 것은 충돌이 아닙니다. 라우팅이 컴포넌트를 배치하고, 지정된 항목이 그것을 구성합니다.
Release가 어디에도 배치하지 않은 하위 aggregate는 빌드를 중단시킵니다. 배치는 두 표기 모두에 걸쳐 판단되므로, 어느 쪽도 하위 모듈에 도달하지 않을 때만 빌드가 중단됩니다. 즉 어떤 경계도 aggregates: 아래에서 그것을 라우팅하지 않고, 어떤 경계도 components: 아래에서 그 컴포넌트를 정규화된 점 경로로 지정하지 않는 경우입니다. 어느 한 표기만으로도 배치되며, 모든 컴포넌트가 개별적으로 지정된 하위 모듈에는 라우팅 항목이 필요하지 않습니다. 수정할 곳은 하위 모듈을 가져온 Aggregate의 aggregates: 블록입니다. 직접 가져온 하위 모듈이면 Release가 배포하는 Aggregate이고, 중첩된 하위 모듈이면 그것을 가져온 하위 모듈 자신의 문서입니다. 진단은 가져오는 문서가 그 항목을 표기한 키로 항목을 지정하므로, 중첩된 하위 모듈의 경우 점 경로가 아니라 로컬 이름으로 표시됩니다.
두 가지 경우는 의도적으로 중단되지 않습니다. 컴포넌트를 제공하지 않는 하위 모듈은 배치할 것이 없습니다. active: 토글이 false로 해석되는 하위 모듈은 애초에 구성되지 않았으므로, 배치할 컴포넌트가 존재하지 않습니다.
부분 배치는 이 규칙에서는 중단되지 않습니다. 하위 모듈은 그 컴포넌트 중 하나라도 경계에 도달하면 배치된 것으로 간주되므로, 그중 하나만 지정해도 하위 모듈은 충족됩니다. 그렇다고 나머지를 빠뜨려도 된다는 뜻은 아닙니다. 경계가 지정하지 않은 각 컴포넌트는 그때 아무것에 의해서도 배치되지 않으며, 아래의 컴포넌트 규칙이 각자의 키에서 이를 보고합니다. 따라서 부분적으로 배치된 하위 모듈은 하위 모듈 단위가 아니라 남겨진 컴포넌트마다 한 번씩 빌드를 중단시킵니다. 하위 모듈 전체를 한 줄로 배치하는 두 표기는 라우팅 항목과 모든 컴포넌트를 지정하는 것이며, 그 중간의 어떤 방식이든 지정한 것만 배치하고 그 이상은 배치하지 않습니다.
Release가 어디에도 배치하지 않은 컴포넌트도 한 단계 안쪽에서 빌드를 중단시킵니다. 위 규칙은 하위 모듈이 경계에 도달했는지를 묻고, 이 규칙은 구성이 담고 있는 모든 컴포넌트에 대해 같은 것을 묻습니다. 컴포넌트는 경계의 components: 아래에 지정되거나, 경계가 라우팅해 들이는 하위 모듈 안에 있음으로써 경계에 도달합니다. 어느 쪽에도 도달하지 않은 컴포넌트는 Release가 선언한 모든 경계 밖에서 렌더링되어 directory, subDirectory, syncWave, 어노테이션 캐스케이드 및 컴포넌트별 infra:를 어디에서도 받지 못합니다. 그래서 빌드는 경계 구성이 닿지 않은 아티팩트를 생성하는 대신 중단되고 해당 컴포넌트를 표시합니다.
두 규칙은 컴포넌트에 하위 모듈이 있는지만 묻는 것이 아니라 그 하위 모듈에 대해 물음으로써 영역을 나눕니다. Release가 어디에도 배치하지 않은 하위 모듈의 컴포넌트는 하위 모듈 규칙에 맡겨지며, 이 규칙은 그 하나의 작성 오류를 모듈이 담은 컴포넌트마다가 아니라 aggregates: 항목에서 한 번 보고합니다. Release가 부분적으로 배치한 하위 모듈의 컴포넌트는 이 규칙의 대상입니다. 하위 모듈 규칙은 그런 모듈을 배치된 것으로 보고 아무것도 말하지 않기 때문입니다. 따라서 경계가 지정하지 않은 각 컴포넌트는 여기서, 그것을 선언한 문서 안의 자신의 키에서 보고됩니다. 그러므로 하위 모듈을 부분적으로 배치하면 지정하려던 것은 정확히 지정되고, 지정하지 않은 각 컴포넌트에 대해서는 알려 줍니다.
그리고 배포되는 Aggregate에 없는 컴포넌트를 지정한 경계 항목도 빌드를 중단시킵니다. 위의 두 규칙은 컴포넌트 쪽에서, 즉 무언가가 그것을 배치했는지로 배치를 판단합니다. 이 규칙은 Release 쪽에서, 즉 이름이 해석되는지로 판단합니다. 아무것으로도 해석되지 않는 항목은 아무것도 배치하지 않으므로, 그 subDirectory, 어노테이션, 컴포넌트별 infra: 및 uses:는 존재하지 않는 컴포넌트를 구성하게 되며, 빌드는 항목이 닿지 않은 배포를 생성하는 대신 중단됩니다. 두 표기 모두 검사됩니다. 경계의 components: 아래 이름은 구성이 완료된 후 컴포넌트가 갖는 id로 해석되고, 라우팅 항목의 components: 아래 이름은 그 하위 모듈 안에서 갖는 로컬 이름으로 해석됩니다. 진단은 항목이 가리킨 id를 보고하는데, 라우팅 표기에서는 이것이 파일 속 이름과 다릅니다. 파일은 로컬 부분을 표기하고 하위 모듈이 그 접두사를 제공하기 때문입니다.
이름은 아무것으로도 해석되지 않을 때만 거부되며, 형태 때문에 거부되지는 않습니다. 한 단계 안쪽 모듈의 컴포넌트는 그 모듈의 접두사를 가지므로 점이 포함된 이름은 일반적인 것입니다. active: 토글이 false로 해석되는 컴포넌트는 계속 지정할 수 있습니다. 컴포넌트를 끄기 위해 그것을 구성하는 Release를 수정할 필요는 없습니다.
서브시스템은 정규화된 경로에 아무것도 더하지 않으므로, Aggregate가 컴포넌트를 어떻게 그룹화하든 경계는 컴포넌트를 그 이름 그대로 지정합니다. id를 정규화하는 것은 하위 모듈 구성뿐입니다. 배포되는 Aggregate의 컴포넌트는 작성자가 최상위에 작성했든 data라는 서브시스템 안에 작성했든 store입니다. 한 단계 안쪽 모듈의 컴포넌트는 data.store이며, 이때 data는 어떤 서브시스템의 것이 아니라 모듈의 접두사입니다. 따라서 data라는 서브시스템에 있는 컴포넌트를 data.store로 표기한 경계 항목은 아무것도 가리키지 않습니다. 항목 자체가 위 규칙에 따라 중단되고, 대상이었던 컴포넌트도 어떤 경계에도 도달하지 못합니다. 항목을 store로 고치면 둘 다 해결됩니다.
따라서 하위 모듈을 배치하려면 boundaries:가 필요합니다. 단일 범위 형식에는 라우팅 수단이 없고(aggregates:는 spec:이 아니라 경계의 키입니다) 최상위 components: 맵은 정규화되지 않은 이름만 받으므로, 하위 모듈을 가져오는 Aggregate를 배포하는 Release는 boundaries:를 선언합니다.
재귀적 라우팅. aggregates:는 재귀적입니다. 경계의 aggregates: 아래 각 항목은 깊이 중첩된 모듈 구성을 위해 그 자체로 중첩된 aggregates: 맵을 선언할 수 있습니다.
aggregate별 라우팅 블록. 라우팅 항목은 정확히 두 개의 키만 받으며 그 외에는 받지 않습니다. 해당 하위 모듈의 개별 컴포넌트를 구성하는 components:와, 더 깊이 중첩된 모듈을 위한 중첩 aggregates:입니다. annotations:는 경계에 속하며, 컴포넌트별 infra:는 라우팅 항목 자신의 components: 아래 항목에 속합니다.
라우팅 항목 안에서 컴포넌트는 자신의 하위 모듈 안에서 갖는 이름, 즉 data.consumer가 아니라 consumer를 키로 사용합니다. 그곳에서 컴포넌트가 갖는 이름은 그것뿐이기 때문입니다. 정규화된 점 경로는 경계 자신의 components: 맵이 같은 컴포넌트를 지정하는 방식입니다. 두 표기는 서로 바꿔 쓸 수 없으며, 라우팅 항목은 점이 포함된 키를 거부합니다.
boundaries: eu-prod: directory: "deploy/eu-prod" annotations: aggrega.ai/namespace: "finance-zone" aggregates: finance: components: ledger: # the component's name inside the finance module infra: replicas: 3 aggregates: reporting: {} # a module nested inside finance하위 aggregate 자신의 컴포넌트와 Features는 Release에서 다시 선언되지 않습니다. Release는 그것들을 다시 기술하는 대신 라우팅하며, 구성하기 위해서만 이름을 지정합니다.
시간적 순서 지정 — 경계별 syncWave
Release의 각 경계는 선택적으로 정수 syncWave: 필드를 선언할 수 있으며, 이를 통해 Operator는 Developer의 Aggregate를 건드리지 않고 배포 순서를 명시적으로 제어할 수 있습니다. 웨이브 번호는 경계 자체의 속성이며, 아티팩트가 생성될 때 경계의 하위 트리에 포함된 모든 컴포넌트는 해당 경계의 웨이브 값을 상속합니다.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest boundaries: infra: directory: "deploy/infra" syncWave: 0 components: core-vpc: {} postgres-db: {} migrations: directory: "deploy/migrations" syncWave: 1 components: db-migration-task: {} apps: directory: "deploy/apps" syncWave: 2 components: web-server: {} ai-agent: {}웨이브 값의 의미. syncWave:는 부호 있는 정수(양수, 0 또는 음수)입니다. 필드를 생략했을 때의 기본값은 0입니다. 웨이브 값은 상위 경계에서 상속되지 않으며, 기본값이 아닌 웨이브를 원하는 각 경계는 이를 명시적으로 선언합니다. Components는 경계의 웨이브를 재정의할 수 없습니다(웨이브는 개별 컴포넌트가 아니라 공간 단위의 속성입니다).
프로바이더별 생성. 컴파일러는 경계의 웨이브 값을 프로바이더 고유의 형태로 렌더링 출력에 기록합니다. 아래에서는 그중 세 가지 형태를 자세히 설명합니다. terraform을 포함한 모든 표준 라이브러리 프로바이더에서 웨이브가 어떻게 동작하는지는 providers/reference-matrix.md의 “What a boundary’s syncWave does on each provider”에 표로 정리되어 있습니다.
- Kubernetes(helm / helm-chart 프로바이더). 웨이브가
0이 아닌 경우, helm 프로바이더가 경계에 대해 렌더링하는 모든 Kubernetes 리소스에는 GitOps 표준argocd.argoproj.io/sync-wave: "<N>"어노테이션이 붙습니다. Helm 훅에는 추가로helm.sh/hook-weight: "<N>"어노테이션이 붙어 동일한 웨이브 값이 Helm 자체의 pre/post-install 순서를 결정합니다. ArgoCD는 sync-wave 어노테이션을, Helm은 훅의 weight를 읽고, 각각 그에 따라 리소스 적용 순서를 정합니다. helm-chart 프로바이더는 소스 차트의 템플릿을 작성자가 쓴 그대로 복사하므로, 하위 차트 자체의 리소스는 해당 템플릿이 웨이브를 쓴 경우에만 웨이브를 가집니다. helm-chart 프로바이더가 추가하는$import:로 로드된 아티팩트에는argocd.argoproj.io/sync-wave가 붙고helm.sh/hook-weight는 붙지 않습니다(providers/helm-chart.md참조). - Compose. 경계가 렌더링되는 compose 파일의 모든 서비스는
depends_on을 통해 같은 파일에 기여한 직전 웨이브의 서비스를 기다립니다. 대상이healthcheck를 선언한 경우에는 대상의 상태(health)를, 선언하지 않은 경우에는 대상의 시작을 기준으로 합니다. 따라서 웨이브는 한 파일의 서비스 순서만 정하며 그 밖의 것에는 영향을 주지 않습니다. 별도의docker-compose.yaml파일로 렌더링되는 경계들은 별개의 compose 프로젝트이며, 이들의 순서를 정하는 것은 운영자의 몫입니다.uses:엣지는 웨이브와 함께 계속해서 엣지별 순서를 표현합니다.providers/compose.md를 참조하십시오. - CloudFormation. 조립된 스택 템플릿의 모든 리소스는
DependsOn을 통해 같은 스택에 기여한 직전 웨이브의 리소스에 의존합니다. 따라서 웨이브는 리소스가 생성되는 순서와, 그 역순으로 삭제되는 순서를 정합니다. 이는 준비 상태(readiness) 순서가 아닙니다. 스택 템플릿에는 리소스가 서비스 가능한 상태라는 개념이 없습니다. 프래그먼트 자체의DependsOn은 대체되지 않고 확장됩니다. 다른 스택으로 조립되는 Components는 범위 밖이며, 두 스택의 순서를 정하는 것은 운영자의 몫입니다.providers/cloudformation.md를 참조하십시오.
웨이브 작성 단위와 배포 단위. 경계는 웨이브 작성 단위입니다. 배포 단위는 컴포넌트가 생성되는 조립 경로이며, 기본적으로 경계와 1:1이지만, directory:를 공유하는 두 형제 경계는 하나의 조립된 출력(하나의 Chart.yaml, 하나의 docker-compose.yaml)으로 합쳐집니다. 이 경우 조립된 출력에는 여러 웨이브의 리소스가 포함될 수 있습니다. 이를 읽는 ArgoCD Application은 Application 안에서 각 리소스를 해당 리소스가 가진 sync-wave 어노테이션에 따라 정렬합니다. helm에서는 0이 아닌 웨이브로 렌더링된 모든 리소스가, helm-chart에서는 $import:로 로드된 아티팩트만 이 어노테이션을 가지며, 하위 차트 자체의 템플릿은 작성자가 쓴 내용을 유지합니다. 경로 간 Application 순서 지정은 운영자의 CI가 담당할 부분입니다.
사용 사례. 한 경계의 시작이 다른 경계의 사전 완료에 의존할 때마다 웨이브 순서가 중요합니다. 대표적인 패턴은 웨이브 0의 infra 경계(VPC + 데이터베이스), 웨이브 1의 migrations 경계(스키마 마이그레이션 작업), 웨이브 2의 apps 경계(마이그레이션된 스키마를 사용하는 애플리케이션)입니다. 명시적인 웨이브가 없으면 세 경계가 모두 동시에 배포되어, 마이그레이션이 완료되기를 기다리는 동안 애플리케이션이 크래시 루프에 빠집니다.
DAG 실행 모델, 시간적 순서 지정을 Aggregate가 아닌 Release에 두는 이유, 웨이브 작성 단위와 배포 단위의 구분 등 전체 아키텍처적 설명은 architecture/12-day-two-lifecycles.md §1을 참조하십시오.
Feature 연결
Release는 Features를 boundary 범위(광범위한 정책)와 컴포넌트별 범위(정밀한 대상 지정) 모두에서 연결할 수 있으며, 실행은 architecture/10-compilation-pipeline.md에 정의된 5계층 양파 모델(5-Tier Onion Model)을 따릅니다. Release에 선언된 Features는 type, infra, uses를 제공하며, values는 선언할 수 없습니다(위의 스키마 수준 제약 조건 참조).
boundary에 연결된 Feature는 직접 선택한 인스턴스 이름을 키로 가지며, 그 이름은 . 또는 ..일 수 없습니다. 각 기여자에게 고유한 디렉터리를 부여하는 provider — modules/ 아래의 terraform, charts/ 아래의 helm-chart — 에서는 boundary 수준 Feature의 파일이 인스턴스 이름만으로 된 디렉터리에 기록되는데, 두 이름 모두 고유한 디렉터리가 될 수 없습니다. 이 경우 빌드는 Release, boundary, 인스턴스를 명시하며 중단됩니다. audit.v2처럼 점을 포함하기만 한 이름은 일반적인 이름입니다.
features:는 두 범위 모두에서 Release의 유일한 연결 지점이며, Aggregate에서도 마찬가지입니다. 자격 증명은 feature.aggrega.ai/kind: secret 레이블을 가진 Feature이므로, Operator가 연결하는 자격 증명은 다른 Feature와 마찬가지로 features: 아래에 연결되고, 연결(connection)에서와 똑같이 infra에 해당 시크릿을 명시합니다(엣지별 연결 구성 참조). 이는 Aggregate가 자격 증명 없이 남겨 둔 컴포넌트에 연결하거나, Aggregate가 시크릿을 명시하지 않고 선언한 연결의 크기 지정으로 사용됩니다. 어떤 범위에도 두 번째 연결 키워드는 없으며, 그러한 키워드를 선언한 문서는 로드 시 예상치 못한 속성을 명시하는 envelope 오류와 함께 거부됩니다.
boundary 전체에 연결된 feature는 uses: 블록을 가질 수 있으며, 그 블록은 boundary로 라우팅된 모든 컴포넌트에 투영됩니다. 각 컴포넌트는 feature가 명시한 대상으로의 의존성 엣지를 얻고, 해당 대상들의 provides를 주입받습니다. 이를 통해 동일한 uses: 엣지를 각 컴포넌트에 반복하는 대신, 공유 의존성 — “이 boundary의 모든 컴포넌트는 공유 캐시 / 수집기 / 메시지 버스와 통신한다” — 을 boundary에서 한 번만 표현합니다. Aggregate의 서브시스템 수준 Feature 연결도 같은 방식으로 서브시스템의 컴포넌트 전체에 uses:를 투영합니다. uses는 값이 아니라 토폴로지 연결 선언이므로 Release에서 허용됩니다. 투영은 연결된 Feature의 실행 범위와 무관합니다. FeatureRecipe가 boundary당 한 번 렌더링되는 Feature라도 uses:는 컴포넌트별로 투영하며, 공유 리소스 자체는 한 번만 렌더링됩니다.
단일 컴포넌트에 연결된 feature는 동일한 uses: 블록을 가지며 그 하나의 컴포넌트에서 동일한 엣지를 연결합니다. 컴포넌트는 명시된 각 대상으로의 의존성 엣지를 얻고, 해당 대상들의 provides를 주입받으며, 엣지는 boundary 전체 형태와 똑같이 연결을 출처로 기록합니다. 두 형태는 두 가지 범위의 단일 선언입니다. boundary에 연결하면 그 안의 모든 컴포넌트를, 컴포넌트에 연결하면 그 하나를 연결하며, 둘 중 무엇을 선택할지는 도달 범위의 문제일 뿐 연결이 하는 일과는 관계가 없습니다. 어느 쪽도 컴퓨트를 생성하지 않습니다. 대상은 Aggregate가 선언한 컴포넌트를 이미 가리켜야 하며, 그렇지 않으면 빌드가 중단됩니다. Feature가 그리는 연결은 자체 연결을 갖지 않습니다. 그 항목은 target과 inject를 받으며, 그곳의 features: 키는 Release 로드 시 거부됩니다.
boundaries: cluster: directory: ./dist/cluster components: api: features: shared_backend: type: core/shared-backend uses: backend: primary: target: db # a component of the assembled graph inject: env: - in: DB_HOST from: host # db's `host` provides reaches api as DB_HOST db: {}대상 표기 방법. 엣지 대상은 조립된 그래프의 컴포넌트를 가리키므로, 대상이 라우팅된 서브 모듈에 속할 때는 항상 정규화된 점 경로로 작성합니다 — store가 아니라 data.store. 이는 연결 자체가 components: 키가 모듈 로컬인 라우팅 항목 아래에 있을 때도 마찬가지입니다. 키는 연결이 어느 컴포넌트에 있는지를 나타내고 대상은 엣지가 어느 컴포넌트에 도달하는지를 나타내며, 그중 두 번째만 그래프 전체 이름입니다. 모듈 로컬 이름으로 작성된 대상은 어떤 컴포넌트와도 일치하지 않으며, 끊어진 엣지가 생성하는 것과 동일한 진단과 함께 중단됩니다.
복합 Release와 extends: 상속
Release는 작성 표면을 상속할 기반 Release를 가리키는 spec.extends:를 선언할 수 있습니다.
참조는 선언하는 Release 옆에 있는 파일에 대한 경로입니다 — ./base-release.yaml 또는 ../shared/base-release.yaml. Release는 배포 측 엔터티이며 카탈로그에 색인되지 않으므로 extends: 참조는 카탈로그를 통해 해석되지 않습니다. 상대 경로가 허용되는 유일한 형식입니다. 레지스트리 좌표로 작성된 참조는 거부되며, 단순 이름도 거부됩니다. 두 경우 모두 진단 메시지에 상대 경로 형식이 제시됩니다. Manifest의 extends:는 가까운 이웃이지만 다르게 읽힙니다. 상대 경로 또는 Release 옆에 있는 Manifest의 단순 metadata.name을 받습니다. 따라서 두 형식은 서로 바꿔 쓸 수 없으며, Manifest에서는 해석되는 단순 이름도 여기서는 해석되지 않습니다. 체인의 각 링크도 같은 방식으로 읽힙니다. 다른 디렉터리에 있는 부모 Release는 지정한 Release가 어디에 있든 자신의 부모를 자기 옆 경로로 지정하며, 이는 해당 Release의 parameters $import:가 그 옆에서 해석되는 것과 똑같습니다. 경로는 Release가 작성하는 모든 경로와 마찬가지로 워크스페이스 안의 Release를 가리켜야 합니다. 워크스페이스 밖에서 지정된 Release의 경우에는 그 Release를 담은 디렉터리 안을 가리켜야 하며, 체인의 모든 링크가 이 제약을 받습니다. 밖으로 벗어나는 경로나 링크를 통해 밖으로 이어지는 경로는 해당 파일을 읽기 전에 거부됩니다.
컴파일러는 Release를 로드할 때 체인을 따라갑니다. 이미 체인에 있는 파일로 되돌아오는 체인, 깊이 한도를 넘는 체인, 아무것도 가리키지 않는 참조는 거부합니다. 그런 다음 체인을 하나의 해석된 Release로 접어 합칩니다.
상속한 것은 키 단위로 교체할 수 있습니다. 하나의 분할 불가능한 값 — 스칼라, 리스트, 템플릿 — 에 도달할 때까지 끝까지 사용자의 값이 우선하며, 그런 값은 통째로 받거나 통째로 교체합니다. 상속한 항목은 null로 작성하여 제거합니다. 이는 확장하는 Component, Feature, Manifest가 따르는 것과 같은 규칙이므로, 하나를 익힌 작성자는 모두를 익힌 셈입니다.
Release에 적용하면 다음과 같습니다. boundaries는 boundary 이름별로, boundary는 키별로 합성되고, components는 컴포넌트 이름별로, infra는 깊게, features는 인스턴스 이름별로 그리고 pillar별로 합성됩니다. 컴포넌트의 uses는 소켓별로 그리고 연결별로 합성되며, 자식이 작성한 target은 상속된 것을 교체하고, 연결의 infra는 키 단위로 합성되며, 연결의 features는 컴포넌트 자체의 features와 같은 규칙에 따라 슬롯별로 그리고 pillar별로 합성됩니다. directory, subDirectory, syncWave 및 Aggregate와 Manifest 포인터는 교체되는 스칼라입니다.
다음 두 가지는 상속되지 않습니다.
- 식별 정보와 출처.
metadata필드는 상속되지 않습니다. 알아 두어야 할 것은metadata.environment입니다. 이 필드는 모든 Release에 필수이며 본질적으로 Release마다 고유하므로, 자식은 부모의 환경이 아닌 자신의 환경을 출처 레이블에 담아 렌더링합니다. - Aggregate 포인터는 재정의할 수 없고 상속됩니다. 자식은
aggregate:를 선언할 수 없으며 — 스키마는 한 문서에extends:와aggregate:가 함께 있는 것을 거부합니다 — 따라서 자식은 기반과 같은 Developer Intent를 배포합니다.
자식은 manifest:를 생략하여 기반의 것을 상속하거나, Late Binding을 위해 재정의할 수 있습니다.
체인 전체에서 하나의 라우팅 형태. boundaries:와 components:는 단일 Release 안에서 상호 배타적이며, 이는 체인 전체에도 적용됩니다. 이름 있는 boundary를 선언하는 기반과 최상위 components를 선언하는 자식은 거부되며, 진단 메시지는 두 파일과 두 키를 모두 제시합니다. 하나의 라우팅 형태를 선택하여 끝까지 사용하십시오.
로컬 개발 브리지 패턴. 대표적인 사용 사례는 개발자가 Aggregate를 포크하거나 boundary 토폴로지를 복제하지 않고 팀의 프로덕션 Aggregate를 로컬에서 실행하는 것입니다. 팀은 프로덕션 Release를 게시하고, 로컬 Release는 이를 extends:하여 Manifest 포인터만 재정의함으로써 클라우드 대상 Recipes를 로컬 대응물로 바꿉니다.
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release environment: production version: "1.0.0"spec: aggregate: my-app manifest: prod-manifest parameters: region: us-east-1 db_size: 100Gi out_dir: prod boundaries: prod: # A directory is a TEMPLATE, not a fixed path. Writing it against a # parameter is what lets a child render somewhere else without # restating the boundary topology. directory: deploy/{{ .parameters.out_dir }} components: api: { infra: { replicas: 5 } } db: {}
---# Local Release (developer-side; inherits everything, swaps the Manifest)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: local-release environment: local version: "1.0.0"spec: extends: ./prod-release.yaml manifest: local-manifest # surgically overrides for local parameters: region: dev-local db_size: 1Gi out_dir: local # the inherited directory resolves here insteadlocal-release는 기반의 boundary 토폴로지, Feature 연결, 컴포넌트 재정의를 상속합니다. 개발자는 local-release.yaml 하나만 유지하고, 프로덕션 구성을 전혀 복제하지 않은 채 aggrega build --release local-release.yaml을 실행합니다.
directory:는 파라미터를 사용해 작성하십시오. directory는 다른 스칼라처럼 상속되므로, 템플릿 변수가 없는 directory를 상속한 자식은 기반과 같은 경로에 렌더링되며, 어떤 명령줄 옵션도 이를 다른 곳으로 돌리지 않습니다. 예를 들어 Recipes만 바꿔 출력을 비교하려는 경우처럼 의도한 것이라면 이는 정당하므로, 빌드는 이를 거부하지 않고 보고한 뒤 계속 진행합니다. 위와 같이 directory를 파라미터로 작성하면 토폴로지를 한곳에 유지하면서도 각 Release의 출력을 각자의 위치로 보낼 수 있습니다.
다중 파일 파라미터 계층화. Release 상속은 다중 파일 파라미터 계층화를 위한 자리입니다. 기반 Release가 공통 파라미터 세트를 제공하고, 환경별 자식이 기반을 extends:하여 달라지는 슬롯을 재정의합니다.
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifest각 자식은 기반에서 상속한 파라미터가 자신의 파라미터와 병합된 결과를 봅니다. 맵 값 파라미터는 자식 키가 우선하는 방식으로 깊게 병합되고, 스칼라 값 파라미터는 자식이 교체하며, 자식이 null로 작성한 키는 빈 값으로 설정되지 않고 제거됩니다.
기반은 파라미터를 import하고 자식은 여전히 개별 키를 재정의할 수 있습니다. 위의 parameters:에서 설명한 두 가지 작성 방식 — 인라인 또는 단일 $import: — 은 체인이 아닌 한 문서에 대한 규칙입니다. 체인의 각 Release는 둘 중 한 방식을 선언하며, 각 Release의 import는 체인을 접어 합치기 전에 해당 Release를 담은 디렉터리를 기준으로 해석됩니다. 따라서 공유 파일을 import하는 기반과 몇 개의 키를 인라인으로 작성하는 자식은 두 인라인 블록과 똑같이 키 단위로 합성됩니다.
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported file오류 유형. 순환하는 extends: 체인, 누락된 부모 포인터, 자식 측 aggregate: 선언은 모두 문제가 된 Release와 스키마 수준 위반을 제시하는 명시적 진단과 함께 워크스페이스 로드를 중단시킵니다. 오류별 메시지 형태는 errors/fatal-halts.md를 참조하십시오.