Provider 아키텍처
provider는 Recipe의 입력 종류를 provider 고유의 manifest 파일로 렌더링합니다. Recipe가 capability: helm, capability: compose 또는 다른 provider 이름을 선언하면, 컴파일러는 그 이름을 제공하는 provider에 렌더링을 디스패치합니다. 이 장에서는 provider가 provider 렌더링 Plugin으로 구현되는 방식, 디스패치가 동작하는 방식, 그리고 컴파일러를 각 provider에 연결하는 plugin 소켓 계약을 다룹니다.
이 장에서 다루지 않는 내용: Recipe가 출력을 생성하는 데 사용하는 세 가지 입력 종류 구성 모델(source: + valuesMapping:, workload:, artifacts: — 각각 인라인 내용 또는 $import:를 받음)입니다. 이 모델은 모든 provider에 걸쳐 공통으로 적용되며, 각 provider가 어떤 입력 종류를 지원하는지 정리한 Provider Capability Matrix를 포함하여 ../../architecture/16-recipe-input-composition.md에서 설명합니다.
provider-rendering Plugin
Provider 렌더링은 pluginType: provider가 지정된 Plugin이 담당합니다. 프로바이더 렌더링 Plugin은 다음과 같습니다:
- 하나 이상의 provider 이름을 담당합니다 —
spec.provider.capabilities에 선언됩니다. Recipe가 지정하는 provider 이름(spec.capability: helm)은spec.provider.capabilities목록에 해당 이름이 포함된 provider-rendering Plugin에 바인딩됩니다. 둘 이상의 Plugin이 같은 대상을 담당하면, 워크스페이스는.aggrega-config.yaml의 provider 바인딩을 통해 그중 하나를 선택합니다. 이 바인딩은aggrega pull시점에 해석되어 lockfile에 기록됩니다. 바인딩이 없고 후보가 정확히 하나이면 그 후보가 사용되며, 바인딩이 없고 후보가 둘 이상이면 후보 플러그인들의 이름을 명시하며 빌드가 명시적으로 중단됩니다. - provider 소켓 메타데이터를 같은 블록에 담습니다 —
spec.provider는 위의 capability 목록과 함께 provider의 나머지 선언을 담습니다.spec.provider.workloadSchema는 플랫폼이 소유한 Workload 종류가 이 provider의 네이티브 출력으로 어떻게 변환되는지를 문서화하는 JSON Schema 2020-12 선언입니다. 표준 라이브러리 카탈로그는 문서화된 변환 계약으로서 합성을 수행하는 provider에 이를 선언합니다.spec.provider.wellKnownAnnotations는 provider가 읽는aggrega.ai/경계 어노테이션을 열거합니다. 합성 입력(workload:) 지원은 provider의 속성으로서 렌더링 시점에 강제되며,workloadSchema의 존재 여부로 결정되지 않습니다.
spec.provider 블록을 포함한 Plugin 엔터티의 전체 필드 수준 작성 표면은 ../entities/plugin.md를 참조하십시오.
프로바이더별 디스패치
모든 Recipe는 spec의 최상위에 정확히 하나의 capability:를 선언합니다. 컴파일러는 이 필드를 읽고 해당 이름을 제공하는 프로바이더로 렌더링을 디스패치합니다. Recipe 하나가 여러 프로바이더를 동시에 대상으로 삼을 수는 없습니다. 다중 프로바이더 구성은 Release 수준에서 이루어집니다. 경계는 여러 프로바이더의 컴포넌트를 함께 담을 수 있으며, 경계의 평가된 어셈블리 경로에 있는 각 프로바이더의 기여 요소는 독립적으로 어셈블됩니다. 즉 (path, provider) 튜플마다 하나의 어셈블리가 만들어집니다.
단일 노드의 디스패치 경로는 다음과 같습니다.
- 컴파일러는 대상 프로바이더의 매핑 섹션 아래에서 Manifest의 3단계 조회를 통해 이 노드의 Recipe URI를 해석합니다. Manifest가 프로바이더 축으로 그룹화되어 있기 때문에 “같은 Component, 프로바이더마다 다른 Recipes”가 자연스러운 패턴이 됩니다.
- 해석된 Recipe의
spec.capability가 디스패치할 프로바이더 이름을 식별합니다. - 컴파일러는 해당 이름의 프로바이더를 바인딩합니다. 즉
spec.provider.capabilities목록에 그 이름이 포함된 프로바이더 렌더링 Plugin을 해석하고, 그 Plugin의 게스트를 통해 렌더링합니다. 렌더링은 Wasm 전용이며 대체할 호스트 내 렌더러가 없으므로, 제공하는 Plugin으로 해석되지 않는 프로바이더 이름은 라우팅 시점에 빌드를 명시적으로 중단시킵니다. - 프로바이더는 노드별 렌더 컨텍스트(필러 값,
.context.*프로젝션, Recipe의 입력 종류)와 함께 호출됩니다. - 프로바이더는 렌더링된 출력을 반환합니다. 컴파일러는 렌더링된 파일을 경계의 평가된
directory:와 컴포넌트별subDirectory:를 결합한 값을 키로 하는(path, provider)별 어셈블러로 라우팅합니다. 같은 프로바이더에서 같은 경로로 평가되는 두 경계는 어셈블러를 공유합니다. 대표적인 패턴은 부모 경계 하나와directory: "{{ .parent_boundary.directory }}"를 가진 자식 경계 두 개가 하나의 병합된 어셈블리로 합쳐지는 경우입니다.
Manifest의 프로바이더 축 디스패치 형태는 ../entities/manifest.md를, Recipe 측의 단일 프로바이더 선언은 ../entities/recipe.md를 참조하십시오. (path, provider)별 어셈블리 모델과 평가된 경로를 제어하는 경로 템플릿 변수 허용 목록은 ../path-template-variables.md에 설명되어 있습니다.
Wasm 플러그인 계약
Provider 렌더링은 WebAssembly 샌드박스 안에서 실행됩니다. Go 컴파일러가 호스트이고, provider-rendering Plugin이 게스트입니다. 컴파일러는 각 노드마다 노드의 렌더 컨텍스트를 플러그인에 전달하고, 플러그인은 렌더링한 파일을 반환합니다. 이 계약은 모든 provider에 걸쳐 동일합니다:
- 양방향 모두 정규 바이너리 인코딩을 사용합니다. 컴파일러는 렌더 컨텍스트(노드의 값과 첨부, 파싱된
.workload, 평가된 아티팩트 항목, 해석된.source의 이름만 담은 목록, 경계 메타데이터)를 정규 CBOR(RFC 8949 §4.2.1)로 인코딩하여 플러그인에 전달합니다. 플러그인은 같은 인코딩으로 렌더링한 파일 목록을 진단 정보와 함께 응답합니다. 각 파일은 노드의 출력 루트에 대한 상대 경로와 그곳에 기록할 정확한 바이트로 이루어지며, 선택적으로 파일의 형식을 포함합니다. 하나의 노드를 렌더링하는 것부터 경계를 조립하고 경계 간 링크를 연결하는 것까지 소켓의 모든 export는 양방향으로 이 인코딩을 사용하며, 각 언어의 플러그인 개발 키트가 플러그인을 위해 이를 디코딩하고 인코딩합니다. 이 인코딩으로 된 export의 출력 형태가 아닌 응답은 빌드를 중단시킵니다. 플러그인 계약에 각 export의 페이로드가 설명되어 있습니다. - 파일 시스템 접근 없음. Plugins는 호스트 파일 시스템의 임의 파일을 읽을 수 없습니다. Recipe가 지정하는 소스(레지스트리의 차트, 저장소의 모듈)는 플러그인이 실행되기 전에 컴파일러가 해석합니다. 플러그인은 그 소스의 이름 전용 목록을 받고, 선택한 파일을 호스트 함수를 통해 컴파일러에 요청합니다. 이 호스트 함수는 해당 노드의 소스 아래에 있는 파일에 대해서만 응답합니다.
- 네트워크 접근 없음. Plugins는 결정적이고 밀폐되어 있으며, 자체적으로 연결을 열지 않습니다. 플러그인이 렌더링 중에 필요로 하는 외부 입력(차트의 values가 참조하는 원격 스키마 등)은 컴파일러의 외부 입력 호스트 함수를 통해 요청되며, 이 함수는 워크스페이스가 해당 참조에 대해 고정해 둔 내용으로 응답합니다.
- 결정적 출력. 동일한 입력과 동일한 플러그인 버전이 주어지면 플러그인은 바이트 단위로 동일한 출력을 생성해야 합니다. 이 계약 덕분에 컴파일러의 바이트 단위 동일 출력 보장이 플러그인 계층을 거쳐 끝까지 유지됩니다.
--verify-determinism으로 실행한 빌드는 모든 노드를 두 번 렌더링하고, 노드의 두 렌더링 결과가 다르면 중단됩니다.
컴파일 파이프라인의 다른 Wasm 소켓(거버넌스 소켓의 transform 및 verdict 역할)을 포함하여 더 넓은 확장성 수준의 플러그인 소켓 아키텍처는 ../../architecture/14-extensibility.md에 있습니다.
Aggrega의 표준 라이브러리 프로바이더
helm, helm-chart, compose, terraform, cloudformation 프로바이더가 함께 표준 라이브러리 프로바이더 세트를 이룹니다. 이 프로바이더들은 엔터프라이즈 팀이 자체 프로바이더를 작성하지 않아도 일반적인 배포 대상을 지원합니다.
helm은 세 가지 입력 종류를 모두 지원합니다. sourced(Helm SDK로 가져온 업스트림 Helm 차트로, Recipe의 valuesMapping 출력을 차트의 오버라이드로 사용), synthesized(파싱된 Workload에서 생성되는 평탄한 Kubernetes YAML — Workload의 form에 따라 선택되는 컨트롤러 객체(Deployment, StatefulSet, DaemonSet, Job 또는 CronJob)와 Services 및 PVC), artifacts(차트 출력과 함께 놓이는 독립 YAML 파일)입니다. 세 종류 중 어떤 것을 받는지는 ../../architecture/16-recipe-input-composition.md의 Provider Capability Matrix를 참조하십시오.
helm-chart는 sourced 모드(엄브렐러 차트 구성: 경계당 차트 하나, 컴포넌트당 하위 차트 하나)와 이에 함께 붙는 artifacts:를 두 가지 작성 형식 모두에서 지원합니다. $import:로 로드한 artifacts: 항목은 먼저 Aggrega가 Go 템플릿으로 처리한 뒤 렌더링 전에 차트의 templates/ 디렉터리에 주입되며, 인라인 내용의 artifacts: 항목도 같은 방식으로 평가되어 출처 정보가 병합되지 않은 채 하위 차트 루트에 배치되고, 차트 자체의 템플릿이 Helm의 .Files.Get / .Files.Glob으로 읽습니다. 독립적인 artifacts 전용 Recipe는 이 프로바이더가 선언하는 종류가 아니며, synthesized 종류도 마찬가지입니다. 엄브렐러는 하위 차트를 조율하는 반면, Workload 종류는 각 하위 차트 안에 속하는 말단 개념(helm 프로바이더의 영역)이기 때문입니다.
compose는 sourced(compose 파일을 로드하고 valuesMapping 오버레이를 깊은 병합), synthesized(stateless 및 stateful 형식에 대해 파싱된 Workload에서 compose services: + volumes: + networks:를 생성하며, persistentTemplate에서는 볼륨 처리가 축소되어 레플리카별 PVC가 경고와 함께 하나의 공유 명명 볼륨으로 합쳐짐. daemon, scheduled, task 형식은 compose 매핑이 없어 명시적으로 중단됨), artifacts(최상위 키 services: / networks: / volumes: / configs:가 경계별로 결합된 docker-compose.yaml에 병합되는 compose 조각)를 지원합니다. Artifacts는 다른 두 종류 중 어느 쪽과도 함께 붙을 수 있으며, 독립적인 artifacts 전용 Recipe — source:도 workload:도 없는 artifacts: — 역시 이 프로바이더가 선언하는 종류입니다. 그 조각은 같은 규칙으로 병합되므로, 노드는 선언한 것만 정확히 제공하며 존재하지 않는 컴퓨트를 대신할 Workload가 필요하지 않습니다.
terraform은 sourced(Terraform 모듈을 그대로 벤더링하고, valuesMapping 출력을 경계의 루트 구성에 있는 해당 컴포넌트 module 블록의 인수로 제공)와 artifacts(작성된 HCL 또는 .tf.json 본문을 템플릿이 평가한 대로, 다시 쓰지 않고 생성)를 지원합니다. synthesized 입력 종류는 제공하지 않습니다. 플랫폼 Workload 종류를 임의의 Terraform 리소스로 충실하게 매핑할 방법이 없기 때문입니다. 이 프로바이더는 구성을 생성할 뿐 Terraform을 실행하지 않으며, 런타임에 의존하는 값은 Terraform 런타임이 apply 시점에 해석하는 ${ ... } 보간 문자열로 남습니다.
cloudformation은 경계를 하나의 AWS CloudFormation 스택 템플릿으로 렌더링합니다. 컴포넌트가 작성한 리소스 조각을 하나의 순수 JSON 템플릿으로 조립하고, 각 컴포넌트의 provides를 스택 Outputs로 노출하며, uses 엣지를 스택 내에서는 Fn::GetAtt로, 스택 간에는 Fn::ImportValue / Fn::GetStackOutput으로 연결합니다. sourced 및 artifacts 입력을 지원하며, CloudFormation을 실행하지 않고 구성을 생성합니다. 런타임 전용 값은 CloudFormation 내장 함수로 남습니다.
프로바이더 참조 색인은 각 프로바이더의 참조 페이지로 안내하며, 각 프로바이더가 어떤 입력 종류를 받는지는 ../../architecture/16-recipe-input-composition.md의 기능 매트릭스에서 확인할 수 있습니다.
사용자 정의 provider
자체 provider를 작성하는 엔터프라이즈 팀은 표준 라이브러리와 동일한 패턴을 따릅니다. 먼저 provider-rendering Plugin(pluginType: provider)을 작성하여, 나머지 spec.provider 메타데이터와 함께 이 Plugin이 제공하는 provider 이름을 spec.provider.capabilities에 선언합니다. 그런 다음 위의 렌더링 계약을 구현하는 Wasm 아티팩트를 배포합니다. 컴파일러는 사용자 정의 provider를 표준 라이브러리 provider와 동일하게 취급하며, provider별 디스패치는 Recipe가 선언한 provider 이름을 기준으로 동작합니다.
provider 작성 방법은 나중으로 미루지 않고 문서화되어 있습니다. provider 작성하기에서는 describe() 자체 보고, 빌드, Plugin 엔터티, 연결, 그리고 출력을 직접 읽어 볼 수 있는 렌더링까지, 동작하는 provider 게스트를 처음부터 끝까지 구축합니다. Wasm 플러그인 개발자 가이드는 엔터티와 게시 수명 주기에 대한 레퍼런스이며, 플러그인 계약은 각 소켓의 페이로드와 결과 형태를 설명합니다. 게스트는 플러그인 개발 키트를 사용하여 Go, Rust 또는 TypeScript로 작성합니다.