Aggrega 워크스페이스 구성 스키마
자동 생성된 레퍼런스입니다. 직접 편집하지 말고 게시된 JSON Schema에서 다시 생성하십시오.
스키마 ID: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
aggrega CLI가 읽는 워크스페이스별 구성 파일입니다. .aggrega-config.yaml에 위치합니다. workspace 블록은 루트 표지입니다. 이 블록이 있으면 워크스페이스 루트로 표시되며, 이 블록은 카탈로그 디렉터리만 담습니다. 그 밖의 모든 키는 설정이며 최상위에 위치하고, 다음 분류로 나뉩니다. 콘텐츠를 어디에서 가져오고 어떻게 고정하고 캐시하는지(레지스트리 선택, 오프라인, 자동 pull 및 고정 동작, 아티팩트 및 컴파일된 모듈 캐시 위치와 크기 상한), 콘텐츠를 어떻게 신뢰하는지(서명 및 서명 검증 동작), 작성을 얼마나 엄격하게 판정하는지(규칙별 lint 조절값, 지원 중단 엄격도, 작성 release 힌트), 워크스페이스 전체에 어떤 Wasm 플러그인을 연결하는지(거버넌스, 린터, 임포터, 대상별 provider 렌더링 바인딩), CLI가 어떻게 실행되는지(동시성, 서빙, 데몬 파싱 캐시 제거 상한)입니다. 아래 속성이 완전하고 권위 있는 목록입니다. 이 요약은 키가 아니라 분류를 명시하므로 키를 추가해도 요약이 틀리게 되지 않습니다. 평탄한 최상위 형태이며, apiVersion/kind 봉투가 없고, 카탈로그 콘텐츠와 구별됩니다. 스키마 발전 원칙: 새 최상위 키를 추가하는 것은 SemVer MINOR 상향(추가적 변경)이며, 키를 제거하거나 위치를 옮기거나 제약을 강화하는 것은 SemVer MAJOR 호환성 파괴입니다.
최상위 타입: object
속성
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
workspace | object | 아니요 | 워크스페이스 루트 표식입니다. 이 키가 있는 것만으로 해당 디렉터리가 워크스페이스 루트로 표시되며, 루트를 정의하는 카탈로그 디렉터리, 즉 워크스페이스 자체의 디렉터리와 Release에 별도로 주어진 디렉터리만 담습니다. 루트를 정의하지 않는 모든 설정은 여기가 아니라 최상위에 둡니다. 벤더링된 카탈로그 디렉터리 없이 루트를 표시하려면 workspace: {}를 작성하십시오. |
default_registry | string | 아니요 | 엔터티가 레지스트리를 명시하지 않을 때 엔터티가 게시되고 의존성이 해석되는 기본 OCI 레지스트리입니다. aggrega push는 그곳에 게시하고 aggrega pull은 그곳에서 가져옵니다. 기본값은 hub.aggrega.ai입니다. registries 아래 항목의 name(이 경우 해당 항목의 host를 가리킵니다), 호스트 자체, 또는 호스트 뒤에 /와 저장소 경로를 붙인 값(예: ghcr.io/acme, harbor.example.com/platform)을 작성합니다. 이름이 먼저 매칭됩니다. 한 항목의 name인 값은 호스트처럼 표기되어 있더라도 그 항목의 호스트를 뜻하므로, 게시, 가져오기, 서명 검증 및 레지스트리별 모든 신뢰 설정이 그 하나의 호스트를 사용합니다. 두 항목의 이름과 같은 값은 모호하다는 이유로 거부되며, 이름 뒤에 경로가 붙은 값도 거부됩니다. 이름은 항목의 호스트를 가리킬 뿐 그 아래의 위치를 가리키지 않기 때문입니다. 그 밖의 값은 신뢰 정책이 저장되는 표기로 쓴 호스트여야 합니다. 점을 포함한 소문자 호스트 이름(registry.example.com), localhost, 포트가 붙은 단일 이름(registry:5000), IPv4 주소, 대괄호로 감싼 IPv6 주소([::1]) 중 하나이며, 각각 선택적으로 :port를 붙일 수 있고 스킴, 자격 증명, 공백, 대문자를 포함하지 않습니다. 그 뒤에 선택적으로 저장소 경로를 붙일 수 있습니다. 저장소 경로는 소문자와 숫자로 이루어진 하나 이상의 세그먼트를 /로 이은 것으로, 세그먼트 내부는 ., _, __ 또는 대시로 구분할 수 있고 태그, 다이제스트, 끝의 /는 허용되지 않습니다. 경로는 게시하고 가져오는 위치입니다. 기본 레지스트리를 통해 게시되는 모든 엔터티는 <host>/<path>/ 아래에 게시되고, 이를 통해 해석되는 모든 엔터티는 그곳에서 가져오므로 한쪽이 게시한 것을 다른 쪽이 찾습니다. 경로는 레지스트리의 신뢰 방식에는 결코 관여하지 않습니다. 정책이 적용되는 registries 항목, 로그인, 서명 요구 사항, 신뢰된 ID는 모두 호스트만으로 찾습니다. HTTPS로 접속하는 호스트에서 포트 443은 그 호스트의 기본 포트이므로 이를 작성하면 거부되며, 포트 없이 작성할 표기를 알려 줍니다. localhost와 그 밖의 루프백 주소는 일반 HTTP로 접속하므로 443이 일반 포트이고 그대로 유지됩니다. 빈 값은 기본 레지스트리를 지정하지 않습니다. 이 값은 이 스키마가 아니라 구성을 로드할 때 판정됩니다. 이름이 가리키는 항목이 다른 구성 파일에 선언되어 있을 수 있기 때문입니다. 값은 모든 구성 파일과 AGGREGA_DEFAULT_REGISTRY 환경 변수를 읽은 후에 읽히며, 어느 쪽이 설정했든 같은 문구로 거부되고 해당 파일이나 변수를 명시합니다. 한 번의 호출에서 게시 대상을 지정하는 --registry 플래그도 같은 방식으로 항목 이름과 매칭됩니다. 그 밖의 값은 참조일 수 있으며, 그 참조가 가리키는 호스트는 같은 표기 요건을 따르고 저장소 경로 없이 게시물이 도착하는 위치가 됩니다. 호스트는 표기만으로 판정하며, 이름이 해석되는지나 그곳에서 레지스트리가 응답하는지는 확인하지 않습니다. 기본값: "hub.aggrega.ai" |
offline | 불리언 | 아니요 | true이면 빌드가 어떤 레지스트리에도 접속하지 않고 캐시된 아티팩트와 벤더링된 카탈로그 콘텐츠만 참조합니다. 기본값은 false입니다. 기본값: false |
auto_pull | 불리언 | 아니요 | false(기본값)이면 aggrega build는 읽기 전용입니다. 소스 핀을 기록하지 않으며, 릴리스별 lockfile이 없거나 불완전하면 먼저 aggrega pull --release <release>를 실행하라는 진단과 함께 빌드를 명시적으로 중단합니다. true이면 aggrega build가 빌드 전에 프로세스 내에서 pull 단계를 실행하여 Release의 의존성을 lockfile과 캐시로 해석하므로, Release에 대한 첫 빌드에 별도의 pull 단계가 필요하지 않습니다. 같은 단일 빌드 옵트인은 명령줄에서 aggrega build --auto-pull로도 사용할 수 있으며, lockfile을 기록하는 것은 여전히 pull뿐입니다. offline: true는 pull 단계를 끄지 않습니다. 이 단계는 레지스트리에 접속하지 않고 머신이 이미 가진 것, 즉 캐시와 로컬 카탈로그 디렉터리를 대상으로 실행되며, 어느 쪽에도 없는 참조는 그 참조를 명시한 pull 자체의 거부로 빌드를 중단합니다. 기본값: false |
pin_sources_at_pull | 불리언 | 아니요 | false(기본값)이면 pull은 엔터티 옆에 핀을 기록하지 않습니다. Release가 빌드하는, 이 워크스페이스의 카탈로그 디렉터리에 있는 Recipe 또는 FeatureRecipe에 대해, 엔터티 옆의 entity.lock이 엔터티가 읽는 각 입력(좌표가 완전히 작성된 원격 source:, artifacts 항목이 가져오는 파일, 엔터티 옆에 있는 로컬 source:의 각 파일)의 핀을 기록하고 있지 않으면 중단하며, 엔터티, 각 입력과 그 분류, 그리고 이를 기록하는 단계로 aggrega pin을 명시합니다. 핀 고정은 엔터티 작성자의 단계이므로, 아무도 핀을 고정하지 않은 엔터티는 아직 사용할 준비가 되지 않은 것입니다. true이면 이 워크스페이스의 모든 pull이 같은 엔터티에 대해 대신 그 단계를 실행하여 aggrega pin이 기록하는 것과 같은 entity.lock 바이트를 기록합니다. 다른 사람이 핀을 고정하지 않은 엔터티를 사용하는 워크스페이스는 이렇게 중단하지 않고 핀을 한 번 기록합니다. 자체 lockfile을 채우는 빌드는 pull이며 이 설정을 따릅니다. aggrega pull --pin-sources는 한 번의 호출에 대해 핀을 고정하고 --pin-sources=false는 한 번의 호출에 대해 중단하며, 이 설정과 관계없이 적용됩니다. 카탈로그 디렉터리가 아니라 캐시에서 해석된 엔터티는 lock을 기록할 곳이 없으므로 pull에 의해 핀이 고정되거나 중단되지 않습니다. 기본값: false |
pin_sources_at_push | 불리언 | 아니요 | true이면 이 워크스페이스의 모든 aggrega push가 게시하는 엔터티를 번들링하기 전에 엔터티 작성자의 핀 단계를 실행하므로, 이 단계가 엔터티 옆에 기록하는 entity.lock이 게시물에 포함됩니다. false(기본값)이면 push는 핀 단계를 실행하지 않으며, 그 단계가 기록할 모든 핀을 entity.lock이 기록하고 있지 않은 Recipe 또는 FeatureRecipe를 aggrega pin을 명시하며 거부합니다. 이 단계는 엔터티 옆에 기록하므로 엔터티에 쓰기 가능한 위치가 있는 경우에만 실행되며, push는 문서로 지정된 엔터티를 게시하므로 항상 그런 위치가 있습니다. aggrega push --pin-sources는 한 번의 호출에 대해 핀을 고정하고 --pin-sources=false는 고정하지 않으며, 이 설정과 관계없이 적용됩니다. aggrega pin이 실행하는 것과 같은 단계이며 같은 바이트를 기록합니다. 기본값: false |
artifact_cache_dir | string | 아니요 | 로컬 아티팩트/콘텐츠 캐시 디렉터리입니다(레지스트리 pull, OCI 매니페스트, 컴파일된 픽스처). 기본값은 .aggrega/cache입니다. 관례에 따라 gitignore에 추가해야 합니다. 경로는 명령을 어디서 실행하든 워크스페이스 루트를 기준으로 해석됩니다. 이 설정을 읽는 모든 곳이 그 루트를 기준으로 해석하므로 절대 경로는 결코 도달하지 않는 위치를 가리키게 되어, 절대 경로 값은 구성을 로드할 때 거부됩니다. 캐시는 카탈로그 디렉터리 안에 있을 수 있지만(카탈로그 디렉터리가 흔히 워크스페이스 루트이므로 기본값이 그렇습니다) 카탈로그 디렉터리 자체여서는 안 됩니다. 카탈로그 스캔은 캐시를 건너뛰므로, 카탈로그 디렉터리를 가리키는 값은 그 디렉터리의 내용 전체를 스캔에서 제외합니다. 바로 그 이유로 워크스페이스 루트 자체(. 또는 그것으로 귀결되는 모든 표기)를 가리키는 값은 구성을 로드할 때 거부됩니다. 그 밖의 카탈로그 디렉터리를 가리키는 값은 거부되지 않습니다. 정상적으로 로드되지만 스캔이 그 디렉터리에서 아무것도 찾지 못하므로, 캐시를 workspace.catalog_dirs에 나열된 디렉터리 밖에 두는 것은 직접 확인해야 합니다. 데몬의 메모리 내 파싱 캐시 상한을 정하는 parse_cache, 머신 전체의 컴파일된 모듈 저장소 상한을 정하는 compiled_module_cache와는 다릅니다. 기본값: ".aggrega/cache" |
skip_signature_verification | 불리언 | 아니요 | 서명 검증을 전역적으로, 명시적으로 드러나게 해제하는 옵트아웃입니다. true이면 필수 hub 기준선을 포함한 모든 레지스트리에서 서명 검증이 비활성화됩니다. 비상 조치 및 개발 상황을 위한 것이며, 결코 조용히 적용되지 않습니다. pull이 서명을 검사했을 모든 곳에서 검증이 전역적으로 비활성화되었다는 경고를 표시합니다. 기본값은 false입니다. 기본값: false |
build | object | 아니요 | 빌드 시점의 엄격도 조절값과 작성 힌트입니다. authoring_release는 인라인 진단을 위해 LSP에 current Release 힌트를 제공하고, halt_on_deprecated_severity는 사용 중단된 엔터티를 사용할 때 빌드가 반응하는 방식을 제어하며, yaml_indent는 렌더링되는 모든 YAML 아티팩트의 들여쓰기 너비를 설정합니다. |
plugins | object | 아니요 | 워크스페이스 수준의 Wasm 플러그인 연결입니다. 각 소켓(governance, linter, importer)은 플러그인 참조의 배열을 받으며, 빌드는 각 플러그인의 문서화된 진입 함수를 해당 소켓 계약에 따라 호출합니다. providers 목록은 기능을 그 기능을 제공하는 provider 렌더링 플러그인에 바인딩합니다. |
lint | object | 아니요 | 규칙별 엄격도 조절 항목입니다. |
parse_cache | object | 아니요 | 데몬 파싱 캐시의 제거 상한입니다. 두 상한은 동시에 적용됩니다. LRU 제거 루프는 캐시에 항목이 삽입될 때마다 실행되며, 항목 수와 바이트 합계가 모두 범위 안에 들어올 때까지 가장 오래 사용되지 않은 항목을 제거합니다. 어느 한쪽이 0이면 unbounded on that axis를 뜻하며, 캐시가 한 번의 호출 동안만 유지되는 CI 상황에 유용합니다. 디스크상의 콘텐츠 캐시인 artifact_cache_dir와는 별개입니다. |
compiled_module_cache | object | 아니요 | 디스크상의 컴파일된 모듈 캐시의 크기 상한입니다. 이 캐시는 컴파일러가 재사용하는 머신 코드 저장소로, Wasm 플러그인이 빌드마다 한 번이 아니라 머신마다 한 번 컴파일되도록 합니다. 머신의 모든 워크스페이스가 공유하므로, 머신 전체에 하나의 값을 적용하려면 이 키를 전역 구성 파일에 두어야 합니다. 상한은 호출마다 한 번, 플러그인이 로드되기 전에 적용되며, 나머지가 상한에 맞을 때까지 가장 먼저 컴파일된 항목부터 항목 전체를 제거합니다. 빌드가 컴파일하는 도중에는 적용되지 않습니다. 항목을 제거하면 나중에 다시 컴파일하는 비용만 들 뿐이므로 상한을 낮추어도 안전합니다. aggrega cache status는 저장소의 현재 크기를 보고하고, aggrega cache evict --max-size는 명령줄에서 지정한 상한에 맞춰 필요할 때 저장소를 줄입니다. artifact_cache_dir(pull한 레지스트리 콘텐츠) 및 parse_cache(데몬의 메모리 내 파싱 캐시)와는 별개입니다. |
concurrency | object | 아니요 | 데몬의 요청 디스패치 동시성 설정입니다. 데몬은 단일 stdin 스트림에서 요청을 읽고, 크기가 제한된 요청 큐를 처리하는 워커 풀을 통해 각 요청을 실행합니다. 응답은 완료 순서와 관계없이 요청이 도착한 순서대로 출력됩니다. |
serve | object | 아니요 | IDE 통합이 사용하는 서비스형 컴파일러인 데몬(aggrega serve)의 동작 설정입니다. |
mcp | object | 아니요 | Model Context Protocol 서버(aggrega mcp)의 설정입니다. transport는 서버에 접근하는 방식, 즉 프로세스의 표준 입력과 출력을 통할지 HTTP를 통할지를 선택하며, 어느 쪽을 선택하든 읽힙니다. announce_tools도 두 전송 방식 모두에서 읽힙니다. 클라이언트에게 어떤 도구가 제공되는지는 클라이언트가 서버에 접근한 방식이 아니라 서버의 속성이기 때문입니다. 그 밖의 모든 키는 HTTP 전송 방식이 시작하는 리스너를 구성하며, 서버가 표준 입력과 출력으로 통신하는 동안에는 사용되지 않습니다. listen도 마찬가지이며, 이 경우에는 서버가 오류 스트림에 주소가 사용되지 않는다는 한 줄을 출력할 수 있도록 읽힐 뿐입니다. 아래의 각 키에 어느 쪽인지 표시되어 있습니다. 편집기 백엔드 데몬을 구성하는 serve와는 별개입니다. |
registries | RegistryConfig[] | 아니요 | 레지스트리 호스트를 키로 하는 레지스트리별 설정 및 서명 신뢰 정책입니다. 여기에 나열되지 않은 레지스트리는 기본값을 사용합니다. 즉, 서명이 있으면 검증하고 서명이 없으면 허용합니다. 단, hub.aggrega.ai는 예외로, 명시적인 항목이 없어도 내장된 기준선이 검증된 서명을 요구합니다. 호스트에 대한 명시적인 항목은 해당 호스트의 기준선을 재정의합니다. 기본값: [] |
signing | SigningConfig | 아니요 | 모든 레지스트리에 적용되는 최상위 서명 블록으로, 키리스 서비스 URL, 선택적인 키 기반 키 경로, 그리고 모든 레지스트리에 대한 신뢰 입장(required 및 kinds)을 담습니다. 레지스트리별 signing 블록은 해당 호스트의 엔드포인트 기본값을 재정의하며, 해당 호스트로 범위가 한정된 동일한 required/kinds 입장을 담습니다. 하나의 이름, 하나의 역할이며, 범위는 위치로 정해집니다. 최상위 required/kinds 정책은 구성 캐스케이드 전반에 걸쳐 단조적으로 합성됩니다. 보안: 이 블록에는 비밀 자료가 없습니다. OIDC 신원 토큰은 결코 구성 필드가 아니며(런타임에 플래그나 주변 OIDC 환경을 통해 제공됩니다), key_path는 키 파일의 경로일 뿐 인라인 키 바이트가 아닙니다. |
추가 속성은 허용되지 않습니다.
aggrega-config.workspace
워크스페이스 루트 표식입니다. 이 키가 있는 것만으로 해당 디렉터리가 워크스페이스 루트로 표시되며, 루트를 정의하는 카탈로그 디렉터리, 즉 워크스페이스 자체의 디렉터리와 Release에 별도로 주어진 디렉터리만 담습니다. 루트를 정의하지 않는 모든 설정은 여기가 아니라 최상위에 둡니다. 벤더링된 카탈로그 디렉터리 없이 루트를 표시하려면 workspace: {}를 작성하십시오.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
catalog_dirs | string[] | 아니요 | 이 워크스페이스가 로컬 엔터티를 읽어 오는 선택적 카탈로그 디렉터리로, 레지스트리로 폴백하기 전에 참조됩니다. 각 항목은 파일 시스템 경로이며, 이를 선언한 파일을 기준으로 한 상대 경로로 해석됩니다. 이 목록은 순서가 있는 선착순(first-win) 검색 스택입니다. 어떤 식별자를 가장 먼저 선언한 디렉터리가 그 식별자를 소유하며, 이후 디렉터리에 있는 같은 식별자는 가려집니다. 워크스페이스 루트의 catalog 디렉터리도 나열된 모든 항목 다음에, 그리고 존재하는 경우에만 읽힙니다. 단, 나열된 항목이 이미 이 디렉터리를 포함하고 있으면 그 항목의 일부로 읽힙니다. 따라서 디렉터리를 나열하면 워크스페이스가 이미 읽던 것을 대체하는 것이 아니라 그에 추가됩니다. 이 키를 생략하는 것과 빈 목록으로 작성하는 것은 서로 다른 의미입니다. 생략하면 워크스페이스는 여전히 catalog를 읽고, []로 작성하면 로컬 카탈로그를 전혀 읽지 않으며, 이것이 워크스페이스에 로컬 카탈로그가 없음을 나타내는 방법입니다. releases 아래에 자체 카탈로그 디렉터리가 지정된 Release는 이 목록 대신 그 디렉터리를 읽습니다. 루트 범위: 로컬 카탈로그 디렉터리는 이 워크스페이스 루트에 속하므로 최상위 수준이 아니라 루트 마커에 둡니다. |
catalog_dirs_append | string[] | 아니요 | 유효한 catalog_dirs 목록에 대한 선택적 추가 전용(append-only) 추가 항목입니다. 각 우선순위 계층에서 여기의 항목은 해석된 기본 목록 뒤에 연결되므로, 워크스페이스 설정과 전역 설정이 카탈로그 디렉터리를 서로 가리지 않고 조합할 수 있습니다. 같은 계층에서의 상호작용: 한 계층에 catalog_dirs와 catalog_dirs_append가 모두 지정되면, 그 계층에서 해석된 값은 기본 목록 뒤에 추가 목록이 이어진 것입니다. 기본값: [] |
releases | map of ReleaseCatalogConfig | 아니요 | Release 자체의 선택적 카탈로그 디렉터리로, 여러 카탈로그 변형을 나란히 두고 각 Release를 그중 하나에 대해 빌드하는 워크스페이스를 위한 것입니다. 각 키는 Release 파일이며, 이를 선언한 파일을 기준으로 한 상대 경로로 작성합니다. 각 값은 이 블록에서와 같은 의미의 catalog_dirs와 catalog_dirs_append를 담으며, 그 범위는 해당 Release 하나로 한정됩니다. 여기에 지정된 Release는 이 블록의 목록 대신 자체 catalog_dirs를 읽고 그 뒤에 자체 catalog_dirs_append를 읽습니다. catalog_dirs를 생략한 항목은 이 블록의 목록을 유지하고 그 뒤에 자신의 catalog_dirs_append를 추가합니다. 검색 순서, 워크스페이스 루트의 catalog 디렉터리, 빈 목록의 의미는 이 블록 자체의 목록과 같으며, 이 맵에 지정되지 않은 Release는 이전과 똑같이 이 블록의 목록을 읽습니다. Release는 어떤 방식으로 빌드되든 이 디렉터리를 읽습니다. 터미널에서든, aggrega serve를 통해 에디터에서든, aggrega mcp를 통해서든 마찬가지이며, --catalog 디렉터리는 한 번의 호출에 대해 여전히 이들보다 먼저 검색됩니다. 존재하지 않는 파일을 지정한 항목은 설정을 로드할 때 거부되며, 해당 항목과 파일이 함께 표시됩니다. 따라서 Release의 이름을 바꾸어도 빌드 대상 카탈로그가 조용히 바뀌지 않습니다. 설정 파일 간에 각 Release의 항목은 이 블록 자체의 키와 같은 방식으로 조합됩니다. 해당 Release에 대해 더 가까운 파일의 catalog_dirs가 더 먼 파일의 것을 대체하고, 모든 파일의 catalog_dirs_append는 캐스케이드 순서대로 추가됩니다. AGGREGA_CATALOG_DIRS는 이 블록의 목록을 설정하며 여기의 어떤 항목에도 영향을 주지 않습니다. 단일 Release와 관련되지 않는 작업, 즉 전체 카탈로그의 린트나 검증, 이름으로 엔터티를 조회하는 작업, 에디터가 워크스페이스의 엔터티를 나열하는 작업은 이 항목들이 아니라 이 블록의 목록을 읽습니다. |
추가 속성은 허용되지 않습니다.
aggrega-config.build
빌드 시점의 엄격도 조절값과 작성 힌트입니다. authoring_release는 인라인 진단을 위해 LSP에 current Release 힌트를 제공하고, halt_on_deprecated_severity는 사용 중단된 엔터티를 사용할 때 빌드가 반응하는 방식을 제어하며, yaml_indent는 렌더링되는 모든 YAML 아티팩트의 들여쓰기 너비를 설정합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
authoring_release | string | 아니요 | LSP가 인라인 진단을 위한 current Release 컨텍스트로 취급하는 Release YAML 파일의 경로입니다. 선택 사항입니다. |
yaml_indent | integer | 아니요 | 렌더링되는 모든 YAML 산출물(docker-compose 파일, Helm 차트 템플릿과 values, Kubernetes 매니페스트)의 들여쓰기 너비(공백 수)입니다. 기본값은 해당 형식들의 관례적인 너비인 2입니다. 최솟값: 2. 최댓값: 9. 기본값: 2 |
halt_on_deprecated_severity | string (enum) | 아니요 | 순서 집합 warning < error < retracted에서의 심각도로, 기록된 지원 중단 마커가 이 심각도 이상이면 빌드가 중단됩니다. 이 설정은 마커가 기록되는 두 곳을 모두 관장합니다. 하나는 빌드가 바이트 단위로 동일하게 재현하는 모든 것을 위한 lockfile이고, 다른 하나는 그 옆의 플러그인 신뢰 기록으로, 수락 또는 거부 판정을 반환하는 역할로 연결된 플러그인, 즉 ir-verdict 또는 render-verdict에 연결된 plugins.governance 연결과 모든 plugins.linter 연결을 위한 것입니다. 하나의 설정, 하나의 규칙, 두 저장소입니다. 기본적으로 설정되어 있지 않으며, 설정되지 않으면 기록된 어떤 마커도 빌드를 중단하지 않습니다. 마커는 이미 고정한 버전에 대해 기록되므로, 한 번 성공한 빌드는 계속 성공합니다. 알림과 해석은 별개의 두 축이며, 어느 쪽도 이 설정이 아닙니다. 두 기록 중 하나라도 읽는 모든 인터페이스는 고정된 모든 지원 중단 참조와 마커가 있는 모든 신뢰된 플러그인을 심각도와 관계없이 보고하며, 그 이름과 심각도, 메시지를 표시합니다. 해당 인터페이스는 aggrega build, aggrega validate --release, aggrega lint --release, 에디터용 데몬, 그리고 AI 네이티브 build, describe, validate 도구입니다. 따라서 이 임계값을 높여도 보고되는 내용은 결코 줄어들지 않습니다. 이 설정은 빌드만 관장합니다. aggrega build(및 같은 작업인 AI 네이티브 build 도구)를 중단시키며, 보고 인터페이스는 마커를 표시하고 계속 진행합니다. 참조가 어떤 버전으로 해석되는지에 영향을 주는 것은 retracted 마커뿐이며, 이는 빌드 시점이 아니라 aggrega pull이 버전을 선택할 때 적용됩니다. 허용 값: "warning", "error", "retracted" |
추가 속성은 허용되지 않습니다.
aggrega-config.plugins
워크스페이스 수준의 Wasm 플러그인 연결입니다. 각 소켓(governance, linter, importer)은 플러그인 참조의 배열을 받으며, 빌드는 각 플러그인의 문서화된 진입 함수를 해당 소켓 계약에 따라 호출합니다. providers 목록은 기능을 그 기능을 제공하는 provider 렌더링 플러그인에 바인딩합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
governance | PluginRef[] | 아니요 | 거버넌스 소켓 플러그인입니다. 각 항목은 자신이 연결되는 파이프라인 role(annotation-transform, label-transform, ir-verdict, render-verdict)을 지정합니다. 역할은 플러그인이 내보낼 수 있는 내용과 기본 진입 함수를 모두 결정합니다(annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). 기본값: [] |
governance_append | PluginRef[] | 아니요 | 유효한 governance 목록에 대한 추가 전용 확장입니다. 여기의 항목은 각 우선순위 계층에서 해석된 기본 목록 뒤에 이어 붙여지므로, 워크스페이스 설정과 전역 설정이 거버넌스 연결을 가리지 않고 조합할 수 있습니다. 기본값: [] |
linter | PluginRef[] | 아니요 | 린터 소켓 플러그인입니다. 기본 진입 함수: lint_rules. 린터 플러그인의 export는 lint_로 시작해야 하므로, 이 항목들에서 function:은 해당 접두사를 가진 export를 지정합니다. 기본값: [] |
linter_append | PluginRef[] | 아니요 | 유효한 linter 목록에 대한 추가 전용 확장입니다. governance_append와 같이 가리지 않고 조합하는 의미를 가집니다. 기본값: [] |
importer | FixedEntryPluginRef[] | 아니요 | 임포터 소켓 플러그인입니다. 소켓은 import 진입 함수를 호출하며, 연결 항목은 진입 함수를 지정하지 않습니다. 기본값: [] |
importer_append | FixedEntryPluginRef[] | 아니요 | 유효한 importer 목록에 대한 추가 전용 확장입니다. governance_append와 같이 가리지 않고 조합하는 의미를 가집니다. 기본값: [] |
providers | FixedEntryPluginRef[] | 아니요 | capability별 provider 선택입니다. 각 항목은 하나의 provider capability(Recipe가 spec.capability로 바인딩하는 접두사 없는 capability 이름, 예: helm 또는 compose)를 이를 제공하는 provider 렌더링 플러그인의 접두사 없는 식별자(Plugin 엔터티의 식별자, 즉 metadata.pluginType과 metadata.name을 슬래시로 연결한 것, 예: provider/helm)에 바인딩하며, 버전 고정과 같은 세 가지 형식(접미사 없음, 정확한 버전 :1.0.0, 메이저 호환 범위 :^1.0.0)의 선택적 후행 :version을 붙일 수 있습니다. 이는 둘 이상의 provider 플러그인이 같은 capability를 제공하는 연합 카탈로그에서 모호성을 해소하고 재정의하는 지점으로, 바인딩은 어느 게시자의 플러그인이 해당 capability를 렌더링할지 선택합니다. capability를 제공하는 provider 플러그인이 정확히 하나라면 항목이 필요하지 않습니다. 조합된 목록 전체에서 capability당 정확히 하나의 항목만 허용되며, capability가 중복되면 해석이 명시적으로 중단됩니다. 해석은 pull 시점에 이루어집니다. pull은 해석된 바인딩을 Release별 lockfile에 기록하고 빌드는 lockfile을 읽으므로, pull 이후 여기를 변경해도 다음 pull 전까지는 반영되지 않으며 빌드 출력은 이에 영향을 받지 않습니다(결정적 출력). Release의 모든 빌드와 검증은 Recipe가 해당 capability를 요청하는지와 관계없이 여기의 각 항목도 검사합니다. 빌드가 보유한 플러그인을 지정하지만 그 플러그인이 항목의 capability를 제공하지 않으면 중단되며, 그 플러그인이 제공하는 것과 편집 한 번 거리의 철자가 있으면 그것을 알려 줍니다. capability만 지정하고 플러그인이 없으며 빌드가 읽는 어떤 provider 플러그인도 그 capability를 제공하지 않는 항목은 중단 대신 경고로 보고됩니다. 그것을 제공하는 플러그인은 다른 Release만 읽는 것일 수 있기 때문입니다. 그리고 플러그인이 제공하지만 이 Release가 요청하지 않는 capability에 대한 항목은 유효하며 아무것도 보고되지 않습니다. 항목은 워크스페이스 전체를 위해 작성되고 빌드는 하나의 Release를 대상으로 하기 때문입니다. 콜론을 포함하는 capability는 구성을 로드할 때 거부됩니다. Recipe의 spec.capability는 마지막 콜론까지를 capability로, 그 뒤를 버전 고정으로 읽으므로 어떤 Recipe도 그런 항목에 도달할 수 없기 때문입니다. 명확하게 제공되는 capability에 대한 항목이 없는 것은 오류가 아니지만, 모호하게 제공되는 capability에 대한 항목이 없으면 후보 플러그인을 나열하며 pull이 명시적으로 중단됩니다. 버전 공존은 유지됩니다. 바인딩은 capability별 플러그인 저장소를 선택하고, 각 Recipe의 spec.capability 버전 고정이 그 저장소 내의 버전을 선택하므로, 한 provider의 서로 다른 버전을 고정한 두 Recipes도 공존합니다. 기본값: [] |
providers_append | FixedEntryPluginRef[] | 아니요 | 유효한 providers 목록에 대한 추가 전용 확장입니다. 여기의 항목은 각 우선순위 계층에서 해석된 기본 목록 뒤에 이어 붙여지므로, 워크스페이스 설정과 전역 설정이 provider 바인딩을 가리지 않고 조합할 수 있습니다. governance_append와 같이 가리지 않고 조합하는 의미를 가집니다. capability당 하나의 항목 규칙은 조합된 목록에 적용되므로, 하위 계층에서 이미 바인딩된 capability를 지정하는 추가 항목은 해석을 명시적으로 중단시킵니다. 기본값: [] |
cli | CLIPluginRef[] | 아니요 | 최상위 aggrega 명령으로 설치되는 CLI 확장 플러그인입니다. 각 항목은 해석되고 버전이 고정된 아티팩트 참조와, 설치 시점에 그 참조가 해석된 게스트 바이트의 콘텐츠 다이제스트로 하나의 CLI 플러그인을 고정합니다. 기본 목록이 설정 계층 전반에서 통째로 대체되는 네 가지 공통 소켓 목록과 달리 CLI 목록은 조합됩니다. 전역 설정의 CLI 플러그인은 모든 워크스페이스에 명령을 등록하고, 워크스페이스 설정의 플러그인은 해당 프로젝트에만 등록하며, 둘 다 함께 등록됩니다. 따라서 _append 짝이 필요하지 않습니다. 각 플러그인이 제공하는 명령 이름과 도움말은 플러그인 자체의 자기 기술에서 오며, digest를 키로 하는 디스크상의 describe 캐시에서 읽습니다(캐시가 비어 있으면 게스트 로드로 대체합니다). 목록에는 고정 정보만 담깁니다. 명령 호출 시 해석된 바이트를 다시 해시하여 digest와 비교하며, 불일치하면 명령이 명시적으로 중단되고 다시 고정하도록 안내하므로, 고정 이후 바이트가 바뀐 플러그인이 모르는 사이에 실행되는 일은 없습니다. 기본값: [] |
추가 속성은 허용되지 않습니다.
aggrega-config.lint
규칙별 엄격도 조절 항목입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
publishing_discipline | object | 아니요 | publishing-linter 규칙 집합에 대한 워크스페이스 전역 게이트입니다. allow_* 플래그는 개별 권장하지 않음 검사를 완화합니다. 아티팩트 불변성은 여기서 구성할 수 없습니다. aggrega push는 게시된 버전의 덮어쓰기를 무조건 거부합니다. |
추가 속성은 허용되지 않습니다.
aggrega-config.lint.publishing_discipline
publishing-linter 규칙 집합에 대한 워크스페이스 전역 게이트입니다. allow_* 플래그는 개별 권장하지 않음 검사를 완화합니다. 아티팩트 불변성은 여기서 구성할 수 없습니다. aggrega push는 게시된 버전의 덮어쓰기를 무조건 거부합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
allow_dynamic_refs | 불리언 | 아니요 | true이면 publishing-linter가 카탈로그 콘텐츠에서 $dynamicRef / $dynamicAnchor JSON Schema 구문을 허용합니다. 기본값은 false이며, 이 구문들은 컴파일 타임 스키마 합성을 비국소적으로 만들기 때문에 권장되지 않습니다. Default: false |
allow_id_overrides | 불리언 | 아니요 | true이면 publishing-linter가 엔터티의 스키마 콘텐츠 내 하위 스키마에서 $id 재정의를 허용합니다. 기본값은 false이며, $id 재정의는 리졸버와 JSON Schema 검증기가 모두 의존하는 스키마당 하나의 정규 식별자라는 관례를 깨뜨립니다. Default: false |
allow_direct_x_aggrega_extensions | 불리언 | 아니요 | true이면 빌드 타임 권장하지 않음 검사가 스키마 콘텐츠에 직접 작성된 x-aggrega-selector 및 x-aggrega-inject 키워드를 허용합니다. 기본값은 false이며, 권장되는 작성 방식은 usesSchema(의존성 소켓용) 또는 featuresSchema(자격 증명 바인딩용)이고, 컴파일러가 이를 해당 키워드로 합성합니다. Default: false |
allow_aggrega_ai_prefix | 불리언 | 아니요 | true이면 publishing-linter가 예약된 aggrega.ai/ 및 feature.aggrega.ai/ 네임스페이스를 정규 컨텍스트 밖에서 사용하는 어노테이션 키를 허용합니다. 예약 접두사 규칙은 카탈로그 엔터티의 metadata.annotations를 검사합니다. 접두사 aggrega.ai/ 자체는 플랫폼 고유이며(잘 알려진 어노테이션 키는 이 플래그와 관계없이 면제됩니다), feature.aggrega.ai/ 접두사는 Feature 종류에서만 정규입니다. 기본값은 false입니다. 운영자는 엔터프라이즈 도구가 정당하게 예약 접두사를 사용해야 할 때 이 값을 설정합니다. 이 값은 두 접두사를 함께 완화합니다. Default: false |
allow_nonstandard_names | 불리언 | 아니요 | true이면 publishing-linter가 프로젝트에 문서화된 명명 관례를 따르지 않는 카탈로그 엔터티 이름을 허용합니다. 기본값은 false이며, 일관된 명명은 리졸버, 레이블 선택, 리뷰어의 편의성에 중요한 역할을 합니다. Default: false |
allow_category_mismatches | 불리언 | 아니요 | true이면 publishing-linter가 category-matches-directory 규칙을 억제합니다. 표준 카탈로그 관례에서는 core/false |
allow_undeclared_recipe_provides | 불리언 | 아니요 | true이면 publishing-linter가 provides-declared-by-component 규칙을 억제합니다. 이 규칙은 Recipe가 spec.provides에서 게시하는 키 중, 그 spec.implements가 지정하는 Component가 자신의 spec.schema의 provides 영역에 선언하지 않은 각 키를 보고합니다. 두 가지는 별개의 표면입니다. Recipe가 게시하는 것은 소비자가 받는 값이고, Component가 선언하는 것은 inject from: 참조가 검사받는 출력 계약입니다. 따라서 선언 없이 게시된 키는 그러한 참조를 중단시킵니다. Component가 선언한 것보다 많이 게시하는 Recipe는 그 외에는 빌드 시 허용되므로, 이 결과는 게시 거부가 아니라 권고입니다. 기본값은 false입니다. Default: false |
allow_connection_credential_mismatches | 불리언 | 아니요 | true이면 publishing-linter가 connection-credential-matches-target-key 규칙을 억제합니다. 이 규칙은 aggrega lint --release가 지정한 Release, 즉 해당 Release와 그것이 배포하는 Aggregate, 그리고 그 Aggregate의 인스턴스가 사용하는 Components에 대해 실행합니다. 대상이 호출자에게 요구하는 키를 선언한 각 연결에 대해, 이 규칙은 양 끝이 참조하는 것, 즉 연결이 제시하는 자격 증명과 대상이 자신의 슬롯에 보유한 키를 비교합니다. 양 끝이 서로 다른 시크릿을 지정하는 경우와 한쪽 끝에만 선언된 키를 보고하며, 어느 쪽 값도 인용하지 않습니다. 어느 쪽 끝도 상대의 첨부를 볼 수 없으므로 양 끝은 작성 규율로만 일치합니다. 보통 하나의 parameter가 양쪽에 값을 공급합니다. 빌드는 어느 경우든 이를 허용하므로 이 결과는 권고입니다. 양 끝이 의도적으로 다른 워크스페이스는 여기서 이를 해제합니다. 기본값은 false입니다. Default: false |
추가 속성은 허용되지 않습니다.
aggrega-config.parse_cache
데몬 파싱 캐시의 제거 상한입니다. 두 상한은 동시에 적용됩니다. LRU 제거 루프는 캐시에 항목이 삽입될 때마다 실행되며, 항목 수와 바이트 합계가 모두 범위 안에 들어올 때까지 가장 오래 사용되지 않은 항목을 제거합니다. 어느 한쪽이 0이면 unbounded on that axis를 뜻하며, 캐시가 한 번의 호출 동안만 유지되는 CI 상황에 유용합니다. 디스크상의 콘텐츠 캐시인 artifact_cache_dir와는 별개입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
max_entries | integer | 아니요 | 캐시된 파싱 결과 개수의 상한입니다. 기본값은 1000입니다. 0은 항목 수 축을 비활성화합니다(항목 수로 인한 제거가 발생하지 않음). 최솟값: 0. Default: 1000 |
max_bytes | integer | 아니요 | 캐시가 보유하는 문서의 누적 크기(바이트 단위)의 상한입니다. 기본값은 100000000(100 MB)입니다. 0은 바이트 축을 비활성화합니다(바이트 총량으로 인한 제거가 발생하지 않음). 최솟값: 0. Default: 100000000 |
추가 속성은 허용되지 않습니다.
aggrega-config.compiled_module_cache
디스크상의 컴파일된 모듈 캐시의 크기 상한입니다. 이 캐시는 컴파일러가 재사용하는 머신 코드 저장소로, Wasm 플러그인이 빌드마다 한 번이 아니라 머신마다 한 번 컴파일되도록 합니다. 머신의 모든 워크스페이스가 공유하므로, 머신 전체에 하나의 값을 적용하려면 이 키를 전역 구성 파일에 두어야 합니다. 상한은 호출마다 한 번, 플러그인이 로드되기 전에 적용되며, 나머지가 상한에 맞을 때까지 가장 먼저 컴파일된 항목부터 항목 전체를 제거합니다. 빌드가 컴파일하는 도중에는 적용되지 않습니다. 항목을 제거하면 나중에 다시 컴파일하는 비용만 들 뿐이므로 상한을 낮추어도 안전합니다. aggrega cache status는 저장소의 현재 크기를 보고하고, aggrega cache evict --max-size는 명령줄에서 지정한 상한에 맞춰 필요할 때 저장소를 줄입니다. artifact_cache_dir(pull한 레지스트리 콘텐츠) 및 parse_cache(데몬의 메모리 내 파싱 캐시)와는 별개입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
max_bytes | integer | 아니요 | 컴파일된 모듈 캐시가 디스크에 보유하는 바이트의 상한입니다. 기본값은 53687091200(50 GiB)으로, 체감되도록 의도한 예산이 아니라 무한한 증가를 막는 한계선입니다. 컴파일된 플러그인 하나가 수백 메가바이트에 이르므로 많은 플러그인 버전을 빌드하는 머신에는 기가바이트 단위가 쌓입니다. 이 값은 한 번의 빌드가 컴파일하는 양보다 크게 설정하십시오. 상한은 빌드가 무엇이든 컴파일하기 전에 적용되므로, 단일 빌드 자체의 작업 집합보다 낮은 상한은 모든 빌드가 같은 모듈을 버리고 다시 컴파일하게 만들어 저장소가 아무것도 절약하지 못하게 됩니다. 상한이 먼저 적용되고 그 후 빌드가 컴파일한 것을 기록하므로, 빌드 사이에 저장소가 상한을 넘을 수 있으며 다음 빌드 시작 시 다시 정리됩니다. 0은 상한을 비활성화합니다(저장소가 제한 없이 커지며 자동으로 제거되는 것이 없음). 저장소는 모든 워크스페이스가 공유하는 하나의 디렉터리이므로, 프로젝트 자체 파일에 이 값이 있더라도 이 상한은 프로젝트별이 아닙니다. 값은 다른 모든 키와 같은 방식으로 결정되어 더 가까운 파일이 우선하지만, 저장소의 크기는 여전히 하나뿐입니다. 적용되는 상한은 가장 최근 빌드의 것이므로, 서로 다르게 상한을 둔 두 프로젝트는 번갈아 적용되며, 한쪽의 낮은 상한은 다른 쪽이 컴파일한 머신 코드를 버립니다. 전역 설정 파일에 한 번 설정해야 머신 전체가 하나의 값을 갖게 됩니다. aggrega config show --origin은 각 설정의 유효 값이 어느 파일에서 왔는지 알려 줍니다. 최솟값: 0. Default: 53687091200 |
추가 속성은 허용되지 않습니다.
aggrega-config.concurrency
데몬의 요청 디스패치 동시성 설정입니다. 데몬은 단일 stdin 스트림에서 요청을 읽고, 크기가 제한된 요청 큐를 처리하는 워커 풀을 통해 각 요청을 실행합니다. 응답은 완료 순서와 관계없이 요청이 도착한 순서대로 출력됩니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
pool_size | integer | 아니요 | 요청 큐를 처리하는 워커 수입니다. 기본값은 4이며, 최대 네 개의 요청을 동시에 처리합니다. 요청을 도착 순서대로 하나씩 실행하려면 1로 설정합니다. 1 미만의 값은 데몬이 시작될 때 1로 올려집니다. 최솟값: 1. 기본값: 4 |
추가 속성은 허용되지 않습니다.
aggrega-config.serve
IDE 통합이 사용하는 서비스형 컴파일러인 데몬(aggrega serve)의 동작 설정입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
build_on_inspect | 불리언 | 아니요 | 데몬이 IR 그래프를 검사하는 동안 아티팩트 렌더링 단계를 실행할지 여부입니다. 실행하면 aggrega build가 렌더링 중에 발생시키는 권고도 에디터 문제로 표시됩니다. 빌드를 중단시키는 검사는 추가되지 않습니다. 어느 쪽이든 디스크에는 아무것도 기록되지 않으며(렌더링된 아티팩트, 출력 디렉터리, 잠금 파일 모두 없음), 렌더링 단계는 그래프를 변경하지 않으므로 검사 결과로 그래프가 반환되는 경우 어느 쪽이든 같은 그래프입니다. 기본값은 false로, aggrega inspect와 일치합니다. 터미널 명령은 그래프를 검사하는 동안 렌더링 단계에 도달하지 않으므로 그러한 권고를 발생시키지 않으며, 권고를 발생시키지 않는 에디터 검사는 터미널과 같은 결과를 보여 줍니다. 에디터에 그 추가 계층을 요청하려면 true로 설정합니다. 기본값: false |
lint_on_validate | 불리언 | 아니요 | 데몬이 카탈로그 엔터티를 검증하는 동안 게시 관례 검사를 실행할지 여부입니다. 실행하면 aggrega lint가 해당 엔터티에 대해 보고하는 결과도 에디터 문제로 표시됩니다. 이 결과는 권고입니다. 결과가 보고된 문서도 검증을 통과하며, 그 Release도 여전히 해석되고 렌더링됩니다. 로컬 콘텐츠를 읽는 검사만 실행되며(레지스트리를 조회하지 않고, 아무것도 가져오지 않고, 아무것도 기록하지 않음), 디스크의 파일이 아니라 에디터가 보유한 버퍼를 기준으로 평가되므로 이름을 고치면 저장하기 전에 보고가 사라집니다. 기본값은 false입니다. 에디터 세션은 문서가 올바른지를 보고하며, 두 번째 계층을 요청하기 전까지는 엔터티를 게시할 수 있는지에 대해 아무것도 알리지 않습니다. 이를 요청하려면 true로 설정합니다. 이 키와 관계없이 에디터는 언제든지 검사를 직접 요청할 수 있으며, 이전에 게시된 버전과의 게시 전 비교도 이 방법으로 수행합니다. 기본값: false |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp
Model Context Protocol 서버(aggrega mcp)의 설정입니다. transport는 서버에 접근하는 방식, 즉 프로세스의 표준 입력과 출력을 통할지 HTTP를 통할지를 선택하며, 어느 쪽을 선택하든 읽힙니다. announce_tools도 두 전송 방식 모두에서 읽힙니다. 클라이언트에게 어떤 도구가 제공되는지는 클라이언트가 서버에 접근한 방식이 아니라 서버의 속성이기 때문입니다. 그 밖의 모든 키는 HTTP 전송 방식이 시작하는 리스너를 구성하며, 서버가 표준 입력과 출력으로 통신하는 동안에는 사용되지 않습니다. listen도 마찬가지이며, 이 경우에는 서버가 오류 스트림에 주소가 사용되지 않는다는 한 줄을 출력할 수 있도록 읽힐 뿐입니다. 아래의 각 키에 어느 쪽인지 표시되어 있습니다. 편집기 백엔드 데몬을 구성하는 serve와는 별개입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
transport | string (enum) | 아니요 | 서버에 접근하는 방식입니다. stdio는 프로세스의 표준 입력과 출력으로 프로토콜을 주고받으며, 명령을 하위 프로세스로 실행하는 클라이언트가 이 방식으로 접근합니다. http는 listen이 지정한 주소에서 HTTP로 제공하며, tls가 인증서와 키를 지정하면 HTTPS로 제공합니다. aggrega mcp --transport stdio|http는 한 번의 호출에 대해 이 키를 재정의합니다. 기본값은 stdio이므로, 전송 방식을 지정하지 않은 워크스페이스는 이 블록에 다른 무엇이 있든 표준 입력과 출력으로 제공됩니다. 리스너는 여기서나 명령줄에서 http를 선택한 경우에만 시작됩니다. 그 밖의 값은 구성을 로드할 때 거부됩니다. 호출자가 네트워크로 접근하는 서버의 구성에서는 http를 설정하고, 클라이언트가 서버를 직접 실행하는 경우에는 설정하지 않습니다. stdio가 선택되면 listen의 주소는 사용되지 않으며, 서버는 오류 스트림에 한 줄로 이를 알립니다. 허용 값: "stdio", "http" 기본값: "stdio" |
listen | string | 아니요 | HTTP 전송 방식이 선택되었을 때 리스너가 바인딩하는 주소입니다. 수신할 위치를 지정할 뿐 아무것도 선택하지 않습니다. 전송 방식은 transport가 선택하며, stdio가 선택되면 이 키는 사용되지 않습니다. 두 가지 형식을 허용합니다. TCP 주소에는 host:port, Unix 도메인 소켓에는 unix: 뒤에 파일 시스템 경로를 붙입니다. aggrega mcp --listen <address>는 한 번의 호출에 대해 이 키를 재정의합니다. 기본값은 비어 있으며, HTTP 전송 방식에는 둘 중 한 곳에서 주소를 지정해야 합니다. 둘 다 없으면 이를 선택한 실행은 바인딩 전에 거부됩니다. 평문 주소(tls에 인증서와 키가 없이 접근하는 주소)는 루프백(127.0.0.1, ::1, 또는 이 중 하나로 해석되는 localhost)이나 Unix 소켓에서만 허용되며, 이는 앞단의 프록시가 TLS를 종료할 때 서버가 사용하는 형태입니다. 그 밖의 주소는 바인딩 전에 mcp.tls.cert_file과 mcp.tls.key_file을 언급하며 거부됩니다. authorization.trusted_proxy가 설정된 경우에는 인증서 유무와 관계없이 같은 두 형식만 허용됩니다. 프록시 외에는 아무것도 헤더를 설정할 수 없는 곳에서만 헤더를 자격 증명으로 신뢰할 수 있기 때문입니다. 기본값: "" |
tls | object | 아니요 | 서비스 프로세스 내부에서 TLS를 종료하기 위한 인증서와 키입니다. listen이 지정한 리스너에서 HTTPS를 직접 제공하려면 둘 다 설정합니다. 평문으로 제공하려면 둘 다 설정하지 않으며, 이 경우 listen은 루프백이나 Unix 소켓으로 제한됩니다. 이는 앞단의 프록시가 인증서를 보유할 때 사용할 형태입니다. 두 키 모두 디스크의 파일 경로이며, 어느 쪽도 키 자료를 인라인으로 담지 않습니다. |
allowed_origins | string[] | 아니요 | 요청의 Origin 헤더에서 허용되는 오리진입니다. Origin 헤더가 이 목록에 없는 오리진을 지정한 요청은 403으로 거부되며, 목록에 있는 오리진을 지정하거나 Origin 헤더가 아예 없는 요청은 처리됩니다. 항목은 헤더와 정확히 비교되므로, 각 항목은 브라우저가 오리진을 보내는 방식대로 작성합니다. 소문자 스킴, ://, 소문자 호스트(이름, IPv4 주소, 또는 대괄호로 감싼 IPv6 주소), 그리고 포트가 스킴의 기본값이 아닌 경우 :와 포트를 쓰며, 그 뒤에는 아무것도 붙이지 않습니다. 예: https://app.example.com 또는 http://localhost:3000. 다른 형태의 항목은 브라우저가 보내는 값과 결코 일치할 수 없으므로, 구성 파일을 로드할 때 파일과 항목을 언급하며 거부됩니다. 끝에 /나 경로가 있는 항목(https://app.example.com/), 스킴이 없는 항목(app.example.com), 대문자나 공백이 포함된 항목이 이에 해당합니다. 기본값은 비어 있으므로 어떤 오리진도 허용되지 않으며, Origin 헤더를 보내지 않는 호출자만 처리됩니다. 따라서 브라우저 기반 클라이언트는 여기에 오리진을 등록해야 합니다. 브라우저가 아닌 클라이언트는 그러한 헤더를 보내지 않으므로 항목이 필요 없습니다. 각 항목은 ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$ 패턴과 일치합니다. 기본값: [] |
limits | object | 아니요 | HTTP 리스너가 받아들이는 트래픽에 적용하는 상한으로, 한 호출자가 서비스 프로세스를 고갈시키지 못하게 합니다. 단일 요청의 최대 크기, 동시에 실행되는 요청 수, 한 호출자의 전송 속도를 제한합니다. 어느 것도 끌 수 없습니다. |
authorization | object | 아니요 | 이 서버가 호출자가 제시하는 bearer 토큰에 대해 선언하는 내용입니다. 어떤 인가 서버가 토큰을 발급하는지, 토큰이 발급되는 대상 리소스로서 이 서버가 스스로 게시하는 주소, 선택적으로 그 서버의 검증 키를 읽어 올 파일, 그리고 선택적으로 앞단의 프록시가 대신 토큰을 검증할 때 그 프록시가 설정하는 헤더를 지정합니다. issuer와 resource는 HTTP 전송이 선택될 때마다 필수이며, 이 둘이 없으면 리스너는 바인딩하기 전에 거부됩니다. 표준 입력과 출력으로 통신하는 서버는 이 중 어느 것도 읽지 않습니다. 둘 다 리스너가 제공하는 OAuth 보호 리소스 메타데이터 문서에 게시되며, 이 문서는 HTTP 호출자가 자격 증명을 요구받지 않고 받는 유일한 응답입니다. 클라이언트는 토큰을 어디서 얻을지 알아내기 위해 이 문서를 읽기 때문입니다. 이 블록에는 비밀 자료가 없습니다. 토큰은 호출자가 보내는 요청에 담아 제시하며 구성 필드가 되는 일은 없고, jwks_file은 서명하는 무언가가 아니라 공개 검증 키를 지정합니다. |
deny_reach | string (enum)[] | 아니요 | 호출자의 토큰 내용과 관계없이 이 서버가 허용하지 않는 도달 범위의 종류입니다. 모든 작업은 자신의 효과가 어디까지 미치는지 선언합니다. 읽거나 렌더링하고 아무것도 남기지 않는 작업은 none, 이 프로세스가 제공하는 워크스페이스 안에 쓰는 작업은 workspace, 게시·서명·철회하는 작업은 registry, 호스트의 모든 워크스페이스가 공유하는 것을 변경하는 작업은 machine입니다. 여기에 종류를 지정하면 그 종류의 모든 도구가 이 서버에서 철회됩니다. 철회된 도구는 모든 호출자에 대해 도구 목록과 describe-capabilities의 응답에서 빠지며, 그래도 호출하면 이 설정을 지목하며 거부됩니다. 어떤 스코프로도 허용될 수 없기 때문입니다. 기본값은 빈 값이므로, 서버는 호출자의 스코프가 허용하는 모든 것을 제공합니다. 이것은 스코프가 호출자별로 정하는 한계 위에 서버가 스스로에게 거는 한계입니다. 읽기만 제공하는 서버는 쓰기 종류 세 가지를 여기에 지정하며, 그러면 모든 스코프를 가진 토큰의 호출자에게도 게시할 수 없습니다. machine을 지정하는 것은 허용되지만 아무것도 바꾸지 않습니다. 그 종류의 도구는 HTTP로는 아예 제공되지 않으며, 이는 설정이 아니라 전송의 속성입니다. 리스너가 시작될 때 읽힙니다. 네 가지 이외의 값은 구성을 로드할 때 거부되며, 변경하려면 재시작해야 합니다. 서버가 표준 입력과 출력으로 통신하는 동안에는 전혀 읽히지 않으며, 이때 호출자는 프로세스를 실행한 사람입니다. 각 항목에 허용되는 값: "none", "workspace", "registry", "machine". Default: [] |
announce_tools | string[] | 아니요 | 이 서버가 알리는 도구로, 도구 목록이 보고하는 이름 그대로 지정합니다. 키를 생략하면 이 서버가 가진 모든 도구가 알려지며, 이는 프로토콜을 따르는 클라이언트가 기대하는 동작입니다. 클라이언트는 전체 도구 목록을 가져와 그중 얼마를 모델에 제시할지 스스로 결정합니다. 목록을 작성하면 정확히 그 도구들만 알려집니다. 빠진 도구는 도구 목록과 describe-capabilities의 응답에서 빠지고, 이름으로 호출하면 이 설정을 지목하며 거부됩니다. 빈 목록을 작성하면 아무것도 알려지지 않습니다. 상대편 클라이언트가 등록할 도구 수에 상한을 두는 경우에 설정하고(일부 클라이언트는 동시에 연결된 모든 서버에 걸쳐 그 상한을 적용합니다), 그 클라이언트에 필요한 도구를 지정합니다. 이 설정은 알려지는 것을 좁힐 뿐 그 이상은 하지 않습니다. 기능을 완전히 철회하는 deny_reach도, 호출자 토큰이 가진 스코프도 넓힐 수 없습니다. 여기에 지정된 도구가 deny_reach가 철회하는 종류이면 도구 목록에서 빠지고 호출 시 그 설정을 지목하며 거부됩니다. 여기에 지정되었지만 호출자의 스코프가 허용하지 않는 도구는 목록에는 남으며, 호출하면 그것을 허용할 스코프를 지목하며 거부됩니다. 모든 이름은 이 바이너리가 가진 도구여야 합니다. 어떤 도구에도 해당하지 않는 이름은 서버 시작 시 거부됩니다. 그렇지 않으면 더 좁은 표면을 요청한 사람이 아무 알림 없이 다른 표면을 제공받게 되기 때문입니다. 별도 프로세스에서 aggrega 명령을 실행하는 cli- 계열의 이름은 두 전송 모두에서 허용되며, HTTP에서는 어떤 호출자에게도 그런 도구가 제공되지 않으므로 아무것도 알리지 않습니다. 두 전송 모두에서 서버 시작 시 읽히므로, 알려지는 집합은 프로세스 수명 동안 고정되고 변경하려면 재시작해야 합니다. |
health | object | 아니요 | 감독자가 이 프로세스가 살아 있는지, 호출에 응답할 준비가 되었는지 묻는 곳입니다. 두 검사는 별도의 주소에서 응답하며 listen이 지정하는 주소에서는 절대 응답하지 않습니다. 엔드포인트에 대한 모든 요청은 bearer 토큰을 담으므로, 거기서 프로브에 응답하면 엔드포인트에 도달할 수 있는 누구에게나 인증 없이 프로세스 상태를 읽게 하고 프로세스에 일을 시킬 수 있는 공짜 수단을 주게 됩니다. 엔드포인트는 /healthz와 /readyz에 대해, 토큰 유무와 관계없이, 제공하지 않는 모든 경로에 주는 것과 같은 404로 응답합니다. |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp.tls
서비스 프로세스 내부에서 TLS를 종료하기 위한 인증서와 키입니다. listen이 지정한 리스너에서 HTTPS를 직접 제공하려면 둘 다 설정합니다. 평문으로 제공하려면 둘 다 설정하지 않으며, 이 경우 listen은 루프백이나 Unix 소켓으로 제한됩니다. 이는 앞단의 프록시가 인증서를 보유할 때 사용할 형태입니다. 두 키 모두 디스크의 파일 경로이며, 어느 쪽도 키 자료를 인라인으로 담지 않습니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
cert_file | string | 아니요 | 리스너가 제시하는 PEM 인증서 체인의 경로로, 프로세스가 시작될 때 읽힙니다. key_file과 함께 설정합니다. 기본값은 빈 값이며, 이 경우 리스너는 평문으로 제공하고 listen은 루프백 또는 Unix 소켓으로 제한됩니다. Default: "" |
key_file | string | 아니요 | cert_file의 인증서에 대한 PEM 개인 키의 경로로, 프로세스가 시작될 때 읽힙니다. 그것과 함께 설정합니다. 파일 경로이며, 인라인 키 자료는 절대 아닙니다. 기본값은 빈 값이며, 이 경우 리스너는 평문으로 제공하고 listen은 루프백 또는 Unix 소켓으로 제한됩니다. Default: "" |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp.limits
HTTP 리스너가 받아들이는 트래픽에 적용하는 상한으로, 한 호출자가 서비스 프로세스를 고갈시키지 못하게 합니다. 단일 요청의 최대 크기, 동시에 실행되는 요청 수, 한 호출자의 전송 속도를 제한합니다. 어느 것도 끌 수 없습니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
max_body_bytes | integer | 아니요 | 리스너가 허용하는 가장 큰 요청 본문 크기(바이트)입니다. 본문이 이를 초과하는 요청은 413으로 거부되며, 본문은 상한을 넘어서 읽히지 않습니다. 기본값은 4194304(4 MiB)로, 저작 문서 전체를 담은 도구 호출보다 훨씬 크고 한 호출자가 프로세스 메모리의 상당 부분을 점유할 수 있는 크기보다는 훨씬 작습니다. 최솟값은 1이므로 상한을 끄는 값은 없습니다. 호출자가 정당하게 더 큰 문서를 보내는 경우 값을 올립니다. 최솟값: 1. Default: 4194304 |
max_concurrent_requests | integer | 아니요 | 리스너가 동시에 실행하는 요청 수입니다. 이미 그만큼의 요청이 처리 중일 때 도착한 요청은 대기열에 넣지 않고 503으로 거부되므로, 호출자는 보이지 않는 작업 뒤에서 기다리는 대신 재시도하라는 응답을 받습니다. 기본값은 16으로, 작은 호스트의 응답성을 유지하면서 여러 동시 도구 호출의 여유를 남깁니다. 더 큰 호스트에서는 값을 올립니다. 최솟값은 1이므로 상한을 끄는 값은 없습니다. 최솟값: 1. Default: 16 |
requests_per_minute | integer | 아니요 | 한 호출자가 1분 동안 보낼 수 있는 요청 수입니다. 서버 단위가 아니라 호출자 단위로, 즉 호출자 토큰이 지정하는 주체 또는 신뢰된 프록시가 주장한 신원을 기준으로 집계되므로, 바쁜 호출자 하나가 다른 호출자의 허용량을 소비할 수 없습니다. 호출자는 이만큼을 한꺼번에 보낼 수 있으며, 이후 허용량은 60 / requests_per_minute초마다 요청 하나씩 꾸준히 다시 채워지고, 남은 허용량이 없을 때 도착한 요청은 429로 거부됩니다. 기본값은 120으로, 지속적으로 초당 2개입니다. 워크스페이스를 구동하는 어시스턴트가 보내는 양보다 훨씬 많으면서도, 루프에 빠진 클라이언트에는 여전히 한계가 됩니다. 최솟값은 1이므로 상한을 끄는 값은 없습니다. 최솟값: 1. Default: 120 |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp.authorization
이 서버가 호출자가 제시하는 bearer 토큰에 대해 선언하는 내용입니다. 어떤 인가 서버가 토큰을 발급하는지, 토큰이 발급되는 대상 리소스로서 이 서버가 스스로 게시하는 주소, 선택적으로 그 서버의 검증 키를 읽어 올 파일, 그리고 선택적으로 앞단의 프록시가 대신 토큰을 검증할 때 그 프록시가 설정하는 헤더를 지정합니다. issuer와 resource는 HTTP 전송이 선택될 때마다 필수이며, 이 둘이 없으면 리스너는 바인딩하기 전에 거부됩니다. 표준 입력과 출력으로 통신하는 서버는 이 중 어느 것도 읽지 않습니다. 둘 다 리스너가 제공하는 OAuth 보호 리소스 메타데이터 문서에 게시되며, 이 문서는 HTTP 호출자가 자격 증명을 요구받지 않고 받는 유일한 응답입니다. 클라이언트는 토큰을 어디서 얻을지 알아내기 위해 이 문서를 읽기 때문입니다. 이 블록에는 비밀 자료가 없습니다. 토큰은 호출자가 보내는 요청에 담아 제시하며 구성 필드가 되는 일은 없고, jwks_file은 서명하는 무언가가 아니라 공개 검증 키를 지정합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
issuer | string | 아니요 | 이 리스너가 받아들이는 토큰을 발급하는 권한 부여 서버의 주소로, 해당 서버가 스스로 밝히는 발급자 식별자 그대로 씁니다. 예: https://login.example.com. 이 값은 보호된 리소스 메타데이터 문서의 authorization_servers 목록에 게시되며, 클라이언트는 이를 통해 이 리스너용 토큰을 어디서 받을지 알게 됩니다. 기본값은 비어 있으며, 이는 사용할 수 있는 값이 아닙니다. 이 값이 스킴과 호스트를 포함한 완전한 주소를 담지 않으면 리스너는 바인딩 전에 거부됩니다. 권한 부여 서버가 이 머신에서 실행되지 않는 한 https 주소여야 합니다. 일반 http는 localhost, 127.0.0.1, ::1 같은 루프백 호스트에만 허용되며, 다른 호스트의 일반 http 발급자는 바인딩 전에 이 키를 지목하고 https 주소를 요구하며 거부됩니다. 이는 키를 발급자에서 읽든, jwks_file에서 읽든, 앞단의 trusted_proxy가 토큰을 검사하든 마찬가지인데, 모든 클라이언트가 토큰을 받으려고 발급자로 보내지기 때문입니다. 기본값: "" |
resource | string | 아니요 | 호출자가 도달하는 그대로 이 서버가 스스로에 대해 게시하는 주소입니다. 예: https://mcp.example.com/mcp. 앞단 프록시가 내세우는 호스트를 포함해 호출자가 실제로 사용하는 주소를 씁니다. 이는 클라이언트가 이 서버용 토큰을 요청할 때 권한 부여 서버에 건네는 식별자이며, 보호된 리소스 메타데이터 문서의 resource 필드로 그대로 게시되기 때문입니다. 그 문서가 제공되는 위치는 호스트와 경로 사이에 /.well-known/oauth-protected-resource를 끼워 넣어 도출합니다. https://mcp.example.com/mcp로 게시된 서버는 문서를 https://mcp.example.com/.well-known/oauth-protected-resource/mcp에서 제공하며, 뒤에 아무것도 붙지 않은 해당 well-known 경로에서도 제공하는데, 이는 클라이언트가 두 번째로 찾아보는 위치입니다. 토큰은 이 주소가 그 토큰이 명시한 대상(audience) 중 하나일 때만 받아들여집니다. 기본값은 비어 있으며, 이는 사용할 수 있는 값이 아닙니다. 이 값이 스킴과 호스트를 포함한 완전한 주소를 담지 않으면 리스너는 바인딩 전에 거부됩니다. 기본값: "" |
jwks_file | string | 아니요 | 이 서버가 받아들이는 토큰을 검증하는 데 쓰는 JSON Web Key Set을 담은 파일의 경로로, 프로세스가 시작될 때 읽습니다. 기본값은 비어 있으며 이것이 일반적인 경우입니다. 키는 issuer에 게시 위치를 물어 그 주소에서 가져오는 방식으로 권한 부여 서버 자체에서 읽으며, 보유한 키 세트에 없는 키 식별자로 서명된 토큰이 도착하면 한 번 다시 읽습니다. 워크스페이스가 오프라인인 경우 이 값을 설정합니다. 이 경우 이 값이 없으면 리스너는 바인딩 전에 거부되는데, 오프라인 워크스페이스는 네트워크 요청을 하지 않아 키를 얻을 다른 방법이 없기 때문입니다. 이때 파일이 받아들여지는 유일한 키를 담으며 권한 부여 서버에는 전혀 접속하지 않습니다. 파일은 공개 검증 키만 담으며 서명하는 것은 절대 담지 않습니다. 상대 경로는 이를 선언한 설정 파일의 디렉터리를 기준으로 해석됩니다. 기본값: "" |
trusted_proxy | object | 아니요 | 여기서 베어러 토큰을 검증하는 대신, 앞단 프록시가 설정하는 헤더에서 호출자가 누구인지 읽습니다. 다음 두 조건이 모두 성립할 때만 설정합니다. 앞단 프록시가 직접 토큰을 검증하고, 그 프록시 외에는 아무것도 리스너에 도달할 수 없어야 합니다. 이 값을 설정하면 listen은 루프백이나 Unix 소켓이어야 하며, 다른 주소는 바인딩 전에 두 설정을 모두 지목하며 거부됩니다. 헤더는 그것을 설정할 수 있는 호출자 집합만큼만 신뢰할 수 있으며, 네트워크가 도달하는 주소에서는 모든 호출자가 원하는 헤더를 설정할 수 있으므로, 그런 주소에서 이 모드로 동작하는 리스너는 모든 호출자가 누구든 자처하도록 허용하게 됩니다. 이 값을 설정하면 토큰을 전혀 읽지 않습니다. Authorization 헤더에서도, 다른 어디에서도 읽지 않으며 키 세트도 가져오지 않습니다. 호출자의 신원은 principal_header의 값이고, 그 헤더가 없는 요청에는 401로 응답하며, 여기서 지정한 두 헤더만 읽습니다. 기본값처럼 생략하면 이 서버가 직접 베어러 토큰을 검증합니다. |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp.authorization.trusted_proxy
여기서 베어러 토큰을 검증하는 대신, 앞단 프록시가 설정하는 헤더에서 호출자가 누구인지 읽습니다. 다음 두 조건이 모두 성립할 때만 설정합니다. 앞단 프록시가 직접 토큰을 검증하고, 그 프록시 외에는 아무것도 리스너에 도달할 수 없어야 합니다. 이 값을 설정하면 listen은 루프백이나 Unix 소켓이어야 하며, 다른 주소는 바인딩 전에 두 설정을 모두 지목하며 거부됩니다. 헤더는 그것을 설정할 수 있는 호출자 집합만큼만 신뢰할 수 있으며, 네트워크가 도달하는 주소에서는 모든 호출자가 원하는 헤더를 설정할 수 있으므로, 그런 주소에서 이 모드로 동작하는 리스너는 모든 호출자가 누구든 자처하도록 허용하게 됩니다. 이 값을 설정하면 토큰을 전혀 읽지 않습니다. Authorization 헤더에서도, 다른 어디에서도 읽지 않으며 키 세트도 가져오지 않습니다. 호출자의 신원은 principal_header의 값이고, 그 헤더가 없는 요청에는 401로 응답하며, 여기서 지정한 두 헤더만 읽습니다. 기본값처럼 생략하면 이 서버가 직접 베어러 토큰을 검증합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
principal_header | string | 예 | 앞단 프록시가 호출자의 신원을 넣는 헤더입니다. 예: X-Forwarded-User. HTTP 헤더 이름으로 씁니다. 문자, 숫자, 하이픈과 헤더 이름에 쓸 수 있는 그 밖의 문자(!#$%&'*+.^_|~와 백틱)로 이루어지며, 공백, 콜론 등의 구분자는 쓸 수 없습니다. 다른 형태의 이름은 어떤 요청도 그런 헤더를 담을 수 없으므로, 설정 파일을 로드할 때 해당 파일과 키를 지목하며 거부됩니다. 빈 이름도 거부됩니다. 블록은 앞단 프록시가 검사한다고 말하는데 이 서버가 직접 토큰을 검사하게 되기 때문입니다. 이 모드를 끄려면 trusted_proxy를 생략합니다. 헤더 값은 쓰인 그대로 취하며 아무것과도 비교하지 않습니다. 이 서버가 직접 검증하는 토큰의 주체가 기록만 되고 아무것과도 비교되지 않는 것과 같습니다. 이 모드에서는 이것이 자격 증명의 전부이므로 trusted_proxy를 설정하면 항상 필수이며, 이 헤더 없이 도착한 요청에는 401로 응답합니다. 패턴: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$. |
scopes_header | string | 아니요 | 앞단 프록시가 호출자에게 부여된 스코프를 공백으로 구분해 넣는 헤더입니다. 예: X-Forwarded-Scopes. principal_header와 같은 형태의 HTTP 헤더 이름으로 쓰거나 비워 둡니다. 다른 형태의 이름은 어떤 요청도 그런 헤더를 담을 수 없어 어떤 호출자에게도 스코프가 부여되지 않으므로, 설정 파일을 로드할 때 해당 파일과 키를 지목하며 거부됩니다. 기본값은 비어 있으며, 이는 어떤 호출자에게도 스코프를 주장하지 않습니다. 이름이 무엇이든 이 헤더와 principal_header 외의 헤더는 읽지 않습니다. 패턴: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. 기본값: "" |
추가 속성은 허용되지 않습니다.
aggrega-config.mcp.health
감독자가 이 프로세스가 살아 있는지, 호출에 응답할 준비가 되었는지 묻는 곳입니다. 두 검사는 별도의 주소에서 응답하며 listen이 지정하는 주소에서는 절대 응답하지 않습니다. 엔드포인트에 대한 모든 요청은 bearer 토큰을 담으므로, 거기서 프로브에 응답하면 엔드포인트에 도달할 수 있는 누구에게나 인증 없이 프로세스 상태를 읽게 하고 프로세스에 일을 시킬 수 있는 공짜 수단을 주게 됩니다. 엔드포인트는 /healthz와 /readyz에 대해, 토큰 유무와 관계없이, 제공하지 않는 모든 경로에 주는 것과 같은 404로 응답합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
listen | string | 아니요 | 활성(liveness) 검사와 준비(readiness) 검사에 응답하는 주소이며, listen과 같은 두 가지 형식을 사용합니다. host:port, 또는 unix: 뒤에 파일 시스템 경로를 붙인 형식입니다. 기본값은 비어 있으며, 이 경우 두 번째 리스너가 시작되지 않고 어느 검사도 어디에서도 응답되지 않습니다. 주소를 설정하면 GET /healthz는 프로세스가 실행되는 순간부터 200으로 응답되고, GET /readyz는 워크스페이스가 해석되고 엔드포인트가 바인딩될 때까지 503으로, 그 이후로는 200으로 응답됩니다. 이것이 수퍼바이저에게 필요한 구분입니다. 실행 중인 프로세스가 곧 호출에 응답할 수 있는 프로세스는 아니기 때문입니다. 모든 응답은 본문이 비어 있는 상태 코드이며, 토큰을 요구하지 않고 어떤 헤더도 읽지 않습니다. 이 주소의 다른 경로는 모두 404이고, 이 두 경로에 대한 다른 메서드는 모두 405입니다. listen과 달리 이 주소는 루프백이나 Unix 소켓으로 제한되지 않으며 어떤 주소도 거부되지 않습니다. 이 주소는 그런 주소 중 하나를 가리키도록 하는 것이 본래 용도이며, 선택한 주소에 도달할 수 있는 모든 것이 이 두 응답을 읽을 수 있다는 점에 유의하십시오. 기본값: "" |
추가 속성은 허용되지 않습니다.
정의
ReleaseCatalogConfig
하나의 Release 고유의 카탈로그 디렉터리입니다. workspace 블록이 가지는 것과 같은 두 키를 해당 Release 범위로 한정한 것입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
catalog_dirs | string[] | 아니요 | 이 Release가 워크스페이스의 catalog_dirs 대신 로컬 엔티티를 읽어 오는 카탈로그 디렉터리이며, 각 항목은 이를 선언한 파일을 기준으로 한 상대 경로로 해석됩니다. 워크스페이스의 목록과 같이 순서가 있고 먼저 찾은 것이 우선하는 검색 스택이며, 워크스페이스 루트의 catalog 디렉터리가 존재하고 나열된 항목 중 어느 것도 이를 이미 포함하지 않으면 그 뒤에 읽습니다. 생략하면 Release는 워크스페이스의 목록을 그대로 사용하고, []로 작성하면 로컬 카탈로그를 전혀 읽지 않습니다. |
catalog_dirs_append | string[] | 아니요 | 이 Release의 목록(항목이 자체 catalog_dirs를 작성한 경우 그것, 그렇지 않으면 워크스페이스의 것) 뒤에 추가되는 카탈로그 디렉터리이며, 각 항목은 이를 선언한 파일을 기준으로 한 상대 경로로 해석됩니다. Default: [] |
추가 속성은 허용되지 않습니다.
RegistryConfig
하나의 OCI 레지스트리 호스트로 범위가 한정된 설정 및 서명 신뢰 정책입니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
host | string | 예 | 이 설정이 적용되는 레지스트리 호스트입니다(예: hub.aggrega.ai). push/pull 대상의 레지스트리 호스트와 대조되므로, 그 대조가 이루어지는 표기로 작성합니다. 점을 포함하는 소문자 호스트 이름, localhost, 포트가 뒤따르는 단일 이름(registry:5000), IPv4 주소, 또는 대괄호로 묶은 IPv6 주소이며, 각각 선택적으로 :port를 붙일 수 있습니다. 스킴, 경로, 자격 증명, 공백, 대문자는 포함하지 않습니다. HTTPS로 접근하는 호스트의 443 포트는 해당 호스트의 기본 포트이므로, 이를 작성하면 구성을 로드할 때 거부되며 포트 없이 작성해야 할 호스트를 알려 줍니다. 그렇게 표기한 항목은 결코 조회되지 않기 때문입니다. localhost와 그 밖의 루프백 주소는 일반 HTTP로 접근하므로 그곳에서 443은 일반 포트이며 그대로 유지됩니다. aggrega registry add와 aggrega config init --registry는 인수가 지정하는 호스트를 키로 항목을 만들며, 이 방식으로 표기되지 않은 호스트는 거부합니다. 호스트는 표기만으로 판단합니다. 이름이 해석되는지, 그곳에서 레지스트리가 응답하는지는 확인하지 않습니다. 패턴: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$. |
name | string | 아니요 | 이 레지스트리의 선택적 별칭입니다. 호스트가 식별자이며, name은 레지스트리를 지정하는 모든 곳(예: --registry 또는 default_registry)에서 이 항목의 호스트로 해석되는 편의용 선택자입니다. 별칭은 항목 간에 고유해야 합니다. |
trusted_identities | TrustedIdentity[] | 아니요 | 이 레지스트리에서 가져온 아티팩트에 대해 허용되는 키리스 서명 신원의 OR 집합입니다. 서명의 인증서가 어느 한 항목과 일치하면 서명이 검증됩니다. 키리스 검증 경로에서 사용됩니다. Default: [] |
trusted_deprecation_identities | TrustedIdentity[] | 아니요 | 이 레지스트리에서 가져온 아티팩트에 대한 소급 지원 중단(deprecation) 마커에 서명할 수 있도록 추가로 허용되는 키리스 신원의 OR 집합입니다. 지원 중단 마커는 그 서명이 원래 아티팩트의 서명자 또는 여기의 어느 항목과 일치하면 인정됩니다. 따라서 레지스트리 소유자나 보안 팀이, 아티팩트 자체에 서명하도록 신뢰받지 않고도, 원래 게시자가 더 이상 연락할 수 없는 아티팩트를 철회할 수 있습니다. 지원 중단 탐색 경로에서만 사용되며, 아티팩트 서명에 대한 신뢰 집합을 넓히지는 않습니다. Default: [] |
public_key | string | 아니요 | 키 모드 레지스트리용으로 고정된 cosign 호환 공개 키이며, PEM 블록으로 인라인 작성합니다. -----BEGIN PUBLIC KEY----- 줄(또는 -----BEGIN RSA PUBLIC KEY-----)부터 이에 대응하는 -----END 줄까지의 텍스트로, aggrega registry add --key가 키 파일에서 복사하는 형태와 같습니다. 설정되면 이 레지스트리의 서명은 키리스 신원 대신 이 키에 대해 오프라인으로 검증됩니다. -----BEGIN … PUBLIC KEY----- 줄이 없는 값은 구성 파일을 로드할 때 파일과 항목을 명시하며 거부되고, 실수로 여기에 붙여 넣은 개인 키도 마찬가지입니다. 키는 값에 포함된 PEM 블록에서 읽고 그 블록 앞의 텍스트는 무시하므로, 이 줄은 값의 어느 위치에 있어도 됩니다. 여기서는 그 줄만 확인합니다. 블록에 디코딩 가능한 키가 들어 있는지는 이 레지스트리의 서명을 이 키로 검증할 때 드러납니다. 이 값은 민감 정보로 선언되어 있으므로(x-aggrega-sensitive), 거부된 값, 특히 실수로 고른 개인 키는 절대 인용되지 않습니다. 거부 메시지는 파일, 항목, 그리고 값이 위반한 제약(위의 패턴 또는 string 타입)을 명시하고, 값이 들어갈 자리에는 <redacted>를 표시합니다. 정상적으로 로드된 공개 키는 작성된 그대로 읽고 표시합니다. 패턴: -----BEGIN [A-Z ]*PUBLIC KEY-----. |
trusted_root | string | 아니요 | 에어갭 환경의 키리스 검증을 위해 고정한 Sigstore 신뢰 루트 번들의 선택적 경로입니다. 설정되면 키리스 신뢰 앵커를 네트워크 없이 이 파일에서 로드하고, 비어 있으면 공개(public-good) 신뢰 루트를 가져와 캐시합니다. |
advisory | 불리언 | 아니요 | true이면 이 레지스트리의 서명 검증 실패가 pull을 중단하는 대신 경고로 낮춰집니다. 검증은 여전히 실행되고 실패도 보고되지만, pull은 계속 진행됩니다. 기본값은 false입니다. Default: false |
skip_signature_verification | 불리언 | 아니요 | 호스트별 비상용 서명 검증 해제 스위치로, 전역 스위치와 같은 skip_signature_verification 스위치를 배치 위치에 따라 이 호스트로 한정한 것입니다. 최상위 signing.required 정책을 무력화하지는 않습니다. 조직에서 요구한 서명은 이 스위치와 관계없이 이 호스트에서도 검증되며, 이를 비활성화할 수 있는 것은 전역 스위치뿐입니다. 같은 호스트에서 이 스위치를 레지스트리별 signing.required와 함께 설정하는 것은 허용되며, push 시 필수 서명과 pull 시 검증 건너뛰기를 결합합니다. 이 경우 검증 측에서는 건너뛰기가 우선합니다. 호스트별 필수 설정은 최상위 설정과 달리 호스트별 건너뛰기의 영향을 받기 때문입니다. 기본값은 false입니다. Default: false |
signing | SigningConfig | 아니요 | 이 레지스트리의 서명 블록으로, 키리스 서비스 URL, 선택적 키 경로, 호스트별 신뢰 정책을 담습니다. 엔드포인트 필드는 이 호스트로의 push에 대해 전역 signing 블록을 재정의하며, CLI 플래그는 둘 다를 재정의합니다. required와 kinds는 배치 위치에 따라 해석됩니다. 레지스트리 항목 아래에서는 하나의 신뢰 정책을 이 호스트로 한정하며(범위 내의 서명되지 않은 아티팩트 게시가 거부되고, 서명되지 않은 아티팩트 사용도 거부됨), 이는 최상위 signing 블록이 모든 레지스트리에 대해 가지는 것과 같은 개념입니다. |
추가 속성은 허용되지 않습니다.
SigningConfig
서명 블록입니다. 키리스 서비스 URL, 키 기반 키 파일에 대한 선택적 포인터, 신뢰 입장(required 및 kinds)으로 구성됩니다. 최상위에 두면 모든 레지스트리에 적용되고, registries[] 항목 아래에 두면 해당 호스트에 적용됩니다. 모든 필드는 배치 위치에서 범위를 읽습니다. required는 양방향을 모두 다루는 하나의 신뢰 입장입니다(서명되지 않은 범위 내 푸시는 거부되고, 서명되지 않은 범위 내 풀도 거부됩니다). 보안: 이 블록은 비밀 자료를 담지 않습니다. OIDC ID 토큰은 결코 구성 필드가 아니며(수명이 짧고 런타임에 제공됨), key_path는 키 파일의 경로이지 인라인 키 바이트가 아닙니다. 이는 검증 측의 비대칭을 반영합니다. 검증 측에서는 인라인 public_key가 허용되지만, 서명 측은 키 경로만 가집니다. HTTP로 접근하는 aggrega mcp 서버는 어느 배치 위치의 key_path도 참조하지 않으므로, 그러한 리스너를 통해서는 키 기반 서명에 도달할 수 없습니다. 그 리스너가 응답하는 호출은 해당 호출이 담고 있는 ID 토큰으로만 서명합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
fulcio_url | string | 아니요 | 키리스 서명용 Fulcio 인증 기관 URL입니다. 설정하지 않으면 공용 Fulcio 인스턴스가 사용됩니다. 절대 https URL로 작성합니다. 즉 https://, 호스트, 그리고 선택적으로 포트와 경로로 구성되며 공백이 없습니다(예: https://fulcio.sigstore.dev). 스킴이 없는 값(fulcio.example.com)이나 http://로 시작하는 값처럼 다른 형태의 값은 구성 파일을 로드할 때 파일과 키를 명시하며 거부됩니다. 파일은 그 위에 다른 무엇이 적용되기 전에 검사되므로, AGGREGA_SIGNING_FULCIO_URL, --fulcio-url 플래그, 또는 편집기나 어시스턴트의 게시 요청으로 제공된 동일한 엔드포인트에는 이 형태가 요구되지 않습니다. 패턴: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
rekor_url | string | 아니요 | 키리스 서명용 Rekor 투명성 로그 URL입니다. 설정하지 않으면 공용 Rekor 인스턴스가 사용됩니다. 절대 https URL로 작성합니다. 즉 https://, 호스트, 그리고 선택적으로 포트와 경로로 구성되며 공백이 없습니다(예: https://rekor.sigstore.dev). 스킴이 없는 값(rekor.example.com)이나 http://로 시작하는 값처럼 다른 형태의 값은 구성 파일을 로드할 때 파일과 키를 명시하며 거부됩니다. 파일은 그 위에 다른 무엇이 적용되기 전에 검사되므로, AGGREGA_SIGNING_REKOR_URL, --rekor-url 플래그, 또는 편집기나 어시스턴트의 게시 요청으로 제공된 동일한 엔드포인트에는 이 형태가 요구되지 않습니다. 패턴: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
timestamp_url | string | 아니요 | 키리스 서명용 RFC3161 타임스탬프 기관 URL입니다. 기본값이 없습니다. 설정하지 않으면 어떤 타임스탬프 기관에도 연결하지 않으며, 키리스 서명의 신뢰 시각은 투명성 로그 항목에서 가져옵니다. 절대 https URL로 작성합니다. 즉 https://, 호스트, 그리고 선택적으로 포트와 경로로 구성되며 공백이 없습니다(예: https://tsa.example.com/api/v1/timestamp). 스킴이 없는 값(tsa.example.com)이나 http://로 시작하는 값처럼 다른 형태의 값은 구성 파일을 로드할 때 파일과 키를 명시하며 거부됩니다. 파일은 그 위에 다른 무엇이 적용되기 전에 검사되므로, AGGREGA_SIGNING_TIMESTAMP_URL, --timestamp-url 플래그, 또는 편집기나 어시스턴트의 게시 요청으로 제공된 동일한 엔드포인트에는 이 형태가 요구되지 않습니다. 패턴: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
key_path | string | 아니요 | 오프라인 키 기반 서명을 위해 보유한 ECDSA P-256 개인 키 PEM 파일의 경로입니다. 파일 경로이며, 결코 인라인 키 자료가 아닙니다. 설정하지 않으면 키리스 경로가 사용됩니다. HTTP로 접근하는 aggrega mcp 서버는 이 키가 어디에 설정되어 있든, 즉 최상위 signing 블록이든, 레지스트리 항목의 블록이든, AGGREGA_SIGNING_KEY_PATH이든 이 키를 결코 참조하지 않습니다. 그러한 리스너가 응답하는 호출은 호출 자체가 담고 있는 ID 토큰으로만 서명하거나 거부됩니다. 표준 입출력으로 접근하는 서버는 터미널과 마찬가지로 이 키로 서명합니다. |
required | 불리언 | 아니요 | 이 블록의 범위에 대한 하나의 신뢰 입장입니다. true이면 범위 내 아티팩트 종류를 게시할 때 서명이 필요하고(서명되지 않은 범위 내 푸시는 거부됨), 이를 소비할 때도 서명이 필요합니다(서명되지 않은 범위 내 풀은 거부됨). 범위는 배치 위치에서 읽습니다. 최상위 signing 블록에서는 모든 레지스트리를 포괄하고, registries[] 항목의 signing 블록 아래에서는 해당 호스트 하나를 포괄합니다. 하나의 이름, 하나의 역할, 두 가지 범위입니다. 최상위 정책은 구성 캐스케이드 전반에 걸쳐 단조적으로 합성됩니다. 어느 계층이든 true로 설정하면 실효값이 true가 되며, 우선순위가 낮은 어떤 계층도 이를 다시 끌 수 없으므로 일반적인 구성 편집으로는 제거할 수 없습니다. 기본값은 false입니다. 기본값: false |
kinds | string[] | 아니요 | required의 범위를 특정 아티팩트 종류로 한정합니다. 비어 있거나 all 항목 하나만 있으면 서명 가능한 모든 종류를 의미합니다. 그렇지 않으면 입장은 엔터티의 kind: 값(예: Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin)과 일치하는, 나열된 종류에만 정확히 적용됩니다. 최상위 signing 블록에서는 캐스케이드 전반에 걸쳐 합집합으로 합성됩니다. 계층은 범위를 넓힐 수는 있지만 결코 좁힐 수 없습니다. 범위는 required와 마찬가지로 배치 위치에서 읽습니다. 기본값: [] |
추가 속성은 허용되지 않습니다.
TrustedIdentity
허용 가능한 키리스 서명 ID 하나입니다. 인증서 주체(OIDC ID)와 이를 보증한 OIDC 발급자의 쌍으로 구성됩니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
identity | string | 아니요 | 정확한 인증서 주체 대체 이름입니다. 수명이 짧은 서명 인증서에 바인딩된 OIDC ID입니다(예: 유지 관리자 이메일 또는 CI 워크플로 URI). |
identity_regexp | string | 아니요 | 인증서 주체와 대조하는 정규 표현식으로, 정확한 identity 대신 사용합니다(예: 조직 아래의 모든 워크플로를 허용하려는 경우). |
issuer | string | 예 | ID 토큰을 발급한 OIDC 발급자 URL입니다(예: https://accounts.google.com 또는 https://token.actions.githubusercontent.com). |
추가 속성은 허용되지 않습니다.
PluginRef
연결 시 진입 함수를 지정할 수 있는 소켓에 연결되는 Wasm 플러그인에 대한 참조로, governance 및 linter 목록이 이에 해당합니다. 진입점이 고정된 소켓은 대신 FixedEntryPluginRef를 사용하며, 이는 function을 제외한 동일한 필드를 가집니다. uri와 capability는 함께 플러그인을 선택합니다. uri만 지정하면 직접 연결이 됩니다(해당 식별자의 플러그인이 그대로 연결되며, 횡단 소켓의 플러그인은 제공하는 capability를 선언하지 않으므로 이 방식을 사용합니다). capability만 지정하면 해당 capability를 제공하는 플러그인을 해석합니다(Recipe가 spec.capability로 바인딩하는 순수 capability 이름, 예: helm). 둘을 함께 지정하면 모호성이 해소됩니다. 둘 이상의 플러그인이 같은 capability를 제공하는 연합 카탈로그에서 capability는 무엇을 해석할지 지정하고, uri는 해당 플러그인의 순수 식별자로 어느 게시자의 플러그인이 이를 제공할지 선택합니다. function은 소켓의 기본 진입 함수를 재정의하며, 생략하면 소켓에 문서화된 기본값이 적용됩니다. governance 항목에서는 이 기본값이 role에 따라 결정됩니다. role은 governance 연결 역할을 지정하며 governance 항목에서만 읽힙니다. with는 플러그인이 읽는 선택적 연결 시점 입력을 전달합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
uri | string | 아니요 | 플러그인 식별자: Plugin 엔티티의 순수 식별자(<pluginType>/<name> 경로, 예: governance/redact 또는 provider/helm), 로컬 파일 시스템 경로 또는 레지스트리 별칭입니다. 선택 사항이며, 항목은 대신 capability로 플러그인을 선택할 수 있습니다. 선택적으로 끝에 붙는 :version은 다른 버전 고정과 동일한 세 가지 형식(버전 없음, 정확한 버전 :1.0.0, 메이저 호환 범위 :^1.0.0)으로 버전을 고정합니다. |
role | string (enum) | 아니요 | governance 연결이 바인딩되는 파이프라인 역할로, governance 항목에서만 읽힙니다. annotation-transform은 어노테이션 확장 전에 해석된 컴포넌트에 어노테이션을 주입하므로 바인딩된 주입은 Feature 연결이 됩니다. label-transform은 토폴로지 구성 시 토폴로지 그래프 노드 레이블을 자동으로 태깅합니다. ir-verdict는 정적 분석 시 IR 그래프에 대해 수락/거부 판정을 내립니다. render-verdict는 렌더링 시 렌더링된 아티팩트에 대해 판정을 내립니다. 플러그인이 내보낼 수 있는 것은 플러그인이 선언한 종류가 아니라 역할이 결정합니다. 판정 역할의 출력은 판정으로만 읽힐 수 있으며 변경으로 적용되지 않습니다. 변환 역할의 출력은 호스트에 의해 해당 측면(어노테이션 또는 레이블)으로 제한됩니다. 역할은 기본 진입 함수도 선택합니다(annotation-transform → transform_annotations, label-transform → mutate, ir-verdict → verdict_ir, render-verdict → verdict_render). 허용되는 값: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | 아니요 | 이 항목이 플러그인을 선택하는 대상 provider capability로, Recipe가 spec.capability로 바인딩하는 순수 capability 이름입니다(예: helm, compose). 선택 사항이며, 항목은 대신 uri로 플러그인을 직접 연결할 수 있습니다. provider 바인딩은 연합 카탈로그에서 어느 게시자의 플러그인이 capability를 제공할지 선택하는 데 이를 사용하며, 횡단 소켓은 이를 비워 두고 uri로 연결합니다. |
function | string | 아니요 | 소켓의 기본 진입 함수에 대한 선택적 재정의입니다. 생략하면 소켓에 문서화된 기본값이 적용됩니다(governance annotation-transform → transform_annotations, governance label-transform → mutate, governance ir-verdict → verdict_ir, governance render-verdict → verdict_render, linter → lint_rules). 재정의는 플러그인이 선언한 어떤 export든 지정할 수 있으며, 지정한 export는 해당 소켓이 읽는 출력 형태를 반환해야 합니다. 출력에 형태가 선언하지 않은 최상위 필드가 있으면 빌드가 중단되며, 호출된 export와 예상치 못한 필드를 표시합니다. 이 검사는 어떤 최상위 필드 이름이 존재하는지만 읽고, 무엇이 없는지나 그 아래에 무엇이 중첩되어 있는지는 읽지 않으므로 출력에 대한 완전한 검증이 아닙니다. |
with | PluginRefWith | 아니요 | 플러그인이 읽는 선택적 연결 시점 입력입니다. 두 멤버 모두 선택 사항이며 소켓에 구애받지 않으므로 어떤 소켓이든 이 인터페이스를 재사용할 수 있습니다. |
추가 속성은 허용되지 않습니다.
FixedEntryPluginRef
연결이 지정하는 대신 진입점이 고정된 소켓에 연결되는 Wasm 플러그인에 대한 참조로, importer 목록과 providers 바인딩이 이에 해당합니다. function을 제외하고 PluginRef와 동일한 필드를 가집니다. importer 소켓은 소켓 계약이 지정하는 하나의 진입 함수를 호출하고, provider는 선택 가능한 하나의 진입점이 아니라 단계별로 키가 지정된 고정된 export 집합을 구동하므로, 어느 목록에도 function이 지정할 진입점이 없으며 이 키는 허용되지 않습니다. uri와 capability는 함께 플러그인을 선택합니다. uri만 지정하면 직접 연결이 됩니다(해당 식별자의 플러그인이 그대로 연결되며, importer 소켓의 플러그인은 제공하는 capability를 선언하지 않으므로 이 방식을 사용합니다). capability만 지정하면 해당 capability를 제공하는 플러그인을 해석합니다(Recipe가 spec.capability로 바인딩하는 순수 capability 이름, 예: helm). 둘을 함께 지정하면 모호성이 해소됩니다. 둘 이상의 플러그인이 같은 capability를 제공하는 연합 카탈로그에서 capability는 무엇을 해석할지 지정하고, uri는 해당 플러그인의 순수 식별자로 어느 게시자의 플러그인이 이를 제공할지 선택합니다. role은 여기서 허용되지만 이 형태를 사용하는 어느 목록에서도 읽히지 않습니다. 이 키가 지정하는 governance 연결 역할은 PluginRef를 사용하는 governance 항목에서 읽히므로, 이 항목들에 설정된 역할은 아무 효과가 없습니다. with는 플러그인이 읽는 선택적 연결 시점 입력을 전달합니다. provider 바인딩은 대신 Recipe에서 렌더링 구성을 가져오므로, provider 바인딩의 with:는 로드 시 거부됩니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
uri | string | 아니요 | 플러그인 식별자: Plugin 엔티티의 순수 식별자(<pluginType>/<name> 경로, 예: governance/redact 또는 provider/helm), 로컬 파일 시스템 경로 또는 레지스트리 별칭입니다. 선택 사항이며, 항목은 대신 capability로 플러그인을 선택할 수 있습니다. 선택적으로 끝에 붙는 :version은 다른 버전 고정과 동일한 세 가지 형식(버전 없음, 정확한 버전 :1.0.0, 메이저 호환 범위 :^1.0.0)으로 버전을 고정합니다. |
role | string (enum) | 아니요 | governance 연결 역할입니다. 이 형태를 사용하는 어느 목록도 이를 읽지 않습니다. 역할은 governance 항목에서 읽히며 해당 항목은 PluginRef를 사용하므로, 여기에 설정된 역할은 허용되지만 아무 효과가 없습니다. 허용되는 값은 네 가지 governance 역할이며, 각각의 의미는 PluginRef에 설명되어 있습니다. 허용되는 값: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | 아니요 | 이 항목이 플러그인을 선택하는 대상 provider capability로, Recipe가 spec.capability로 바인딩하는 순수 capability 이름입니다(예: helm, compose). 선택 사항이며, 항목은 대신 uri로 플러그인을 직접 연결할 수 있습니다. provider 바인딩은 연합 카탈로그에서 어느 게시자의 플러그인이 capability를 제공할지 선택하는 데 이를 사용하며, 횡단 소켓은 이를 비워 두고 uri로 연결합니다. |
with | PluginRefWith | 아니요 | 플러그인이 읽는 선택적 연결 시점 입력입니다. 두 멤버 모두 선택 사항이며 소켓에 구애받지 않으므로 어떤 소켓이든 이 인터페이스를 재사용할 수 있습니다. |
추가 속성은 허용되지 않습니다.
CLIPluginRef
최상위 aggrega 명령으로 설치되는 고정된 CLI 확장 플러그인입니다. 명령이 해석하고 실행하는, 해석이 완료되고 버전이 고정된 아티팩트 참조와, 설치 시점에 그 참조가 해석된 게스트 바이트의 콘텐츠 다이제스트로 구성됩니다. 이 둘이 함께 명령이 실행하는 바이트를 정확히 고정합니다. 다이제스트는 또한 게스트를 로드하지 않고 명령의 이름과 도움말을 제공하는 describe 캐시의 키가 됩니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
uri | string | 예 | 명령이 해석하고 실행하는, 해석이 완료되고 버전이 고정된 아티팩트 참조입니다(예: oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0). 설치 시 고정됩니다. |
digest | string | 예 | 설치 시 참조가 해석된 게스트 .wasm 바이트의 콘텐츠 다이제스트로, sha256: 뒤에 바이트의 SHA-256 값을 나타내는 소문자 16진수 64자리를 붙여 씁니다. 이는 aggrega plugin add cli가 기록하는 표기이며, 해석된 바이트를 비교할 때 쓰는 표기입니다. 다른 표기의 다이제스트(sha256: 접두사가 없는 16진수, 대문자, 또는 다른 길이)는 이 값과 결코 일치할 수 없으므로, 구성 파일을 로드할 때 파일과 항목을 명시하며 거부됩니다. 이 다이제스트는 명령이 실행하는 정확한 바이트를 고정하며(이후 해석에서 바이트의 해시가 다르면 명령이 중단됩니다), 게스트를 로드하지 않고 명령의 도움말을 렌더링하는 describe 캐시의 키입니다. 패턴: ^sha256:[0-9a-f]{64}$. |
추가 속성은 허용되지 않습니다.
PluginRefWith
플러그인이 읽는 선택적 연결 시점 입력입니다. 두 멤버 모두 선택 사항이며 이 표면은 범용이므로 어떤 소켓이든 재사용할 수 있습니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
sources | string[] | 아니요 | 호스트가 컴파일 시점에 읽어 플러그인에 전달하는 정의 파일 경로입니다. 각 항목은 선언한 구성 파일의 디렉터리를 기준으로 해석되는 파일 시스템 경로입니다. |
settings | object | 아니요 | 플러그인에 그대로 전달되는 자유 형식 설정 객체입니다. 호스트는 그 형태를 해석하지 않으며, 플러그인이 자신이 읽는 키를 정의합니다. |
추가 속성은 허용되지 않습니다.