콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

구성

aggrega가 설정을 어디에서 읽는지, 그리고 각 설정을 어느 파일에 넣어야 하는지 설명합니다.

간단한 경우

파일 두 개이며, 대부분의 프로젝트에는 그 외에 아무것도 필요하지 않습니다.

프로젝트 안의 파일 하나로, 이름은 .aggrega-config.yaml이며 프로젝트 루트에 있습니다. 이 파일은 이 프로젝트가 빌드되는 방식을 담습니다. 어떤 디렉터리가 vendored 카탈로그 콘텐츠를 담는지, 어떤 플러그인이 어떤 대상을 렌더링하는지, 어떤 lint 규칙이 완화되는지, 로컬 캐시가 어디에 저장되는지입니다. 이 파일은 커밋되므로, 프로젝트를 클론한 팀원도 같은 방식으로 빌드합니다.

이 파일의 workspace: 블록이 해당 디렉터리를 프로젝트 루트로 표시합니다.

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

이 블록은 루트를 정의하는 카탈로그 디렉터리만 담으며, 다른 모든 설정은 그 옆의 최상위 수준에 둡니다. 카탈로그 콘텐츠를 vendoring하지 않는 프로젝트도 블록을 비워서 — workspace: {} — 작성합니다. 블록이 존재한다는 사실이 곧 표시이기 때문입니다.

머신의 전역 파일 하나로, 위치는 ~/.config/aggrega/config.yaml입니다. Windows에서는 APPDATA 환경 변수가 가리키는 디렉터리 안의 aggrega\config.yaml입니다. 해당 머신의 모든 워크스페이스가 이 파일을 거쳐 해석되며, 이 파일은 특정 프로젝트가 아니라 머신에 속하는 설정을 담습니다. 가져오는 레지스트리와 각 레지스트리의 서명 신뢰 정책, 컴파일된 모듈 저장소가 커질 수 있는 크기, 설치한 명령 확장 플러그인 등입니다. 이런 설정은 어디서 작업하든 같으므로, 한 번만 선언하는 것이 핵심입니다. 파일이 있으면 자동으로 로드되고, 없어도 아무 문제가 생기지 않습니다.

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega config init은 이 전역 파일을 대신 작성하여, 레지스트리를 그 레지스트리가 알리는 서명 신뢰 정책과 함께 등록하고, 머신에서 파일이 어디에 있는지와 머신 전체 캐시가 어디에 보관되는지 알려 줍니다. aggrega config show는 현재 적용되는 내용을 출력하고, aggrega config show --origin은 각 설정을 어떤 파일 — 또는 어떤 환경 변수 — 가 결정했는지 알려 줍니다.

비밀 정보는 구성이 아닙니다. 레지스트리 비밀번호와 서명 ID 토큰은 어느 파일에도 필드로 들어가지 않으며, 필요한 시점에 환경 변수나 플래그로 제공됩니다. environment-variables.md를 참조하십시오.

로컬 엔티티를 읽는 위치

자체 카탈로그 콘텐츠 — Component, Feature, Recipe, 라이브러리 종류 중 하나 — 를 보관하는 프로젝트는 그 콘텐츠가 있는 위치를 지정하는 방법이 두 가지이며, 첫 번째 방법은 구성이 전혀 필요하지 않습니다.

프로젝트 루트의 catalog 디렉터리는 무엇이 지정하든 하지 않든 읽힙니다. <project>/catalog/ 아래에 엔티티를 두면 카탈로그를 로드하는 모든 명령이 이를 읽으며, workspace: 블록이 비어 있는 프로젝트에서도 마찬가지입니다. 카탈로그 디렉터리는 재귀적으로 읽히므로, 그 안에서 하위 디렉터리를 어떻게 배치할지는 자유입니다.

workspace.catalog_dirs 아래에 나열된 디렉터리도 읽히며, 이들이 먼저 읽힙니다. 이 목록은 순서가 있는 검색 스택입니다. 어떤 ID를 처음 선언한 디렉터리가 그 ID를 소유하고, 뒤쪽 디렉터리의 같은 ID는 가려집니다. catalog는 나열된 모든 디렉터리 다음에 읽히므로 — 단, 나열된 디렉터리가 이미 이를 포함하면 그 디렉터리의 일부로 읽힙니다 — 디렉터리를 나열하면 기존 것을 대체하지 않고 추가하게 됩니다. 명령줄에서 반복 지정할 수 있는 --catalog <dir>는 둘보다 먼저 읽히며, 여기서 지정한 상대 경로는 어떤 구성 파일도 선언하지 않았으므로 명령을 실행한 디렉터리를 기준으로 해석됩니다. 두 번 이상 지정된 디렉터리 — 명령줄과 목록 양쪽, 또는 목록에 두 번 — 는 처음 지정된 위치에서 한 번만 읽히므로, 그 안의 어떤 것도 자기 자신에 의해 가려진 것으로 보고되지 않습니다. 가려짐은 항상 서로 다른 두 파일이 하나의 ID를 선언하는 경우입니다. 한 디렉터리의 두 가지 표기, 링크를 통한 경로, 그리고 — 대소문자를 구분하지 않는 파일 시스템에서 — 다른 대소문자로 쓴 표기는 모두 그 한 디렉터리를 가리킵니다. 나열된 다른 디렉터리 안에 있는 디렉터리도 별도의 항목으로 읽힙니다. Release마다 카탈로그 변형을 두는 프로젝트는 대신 각 Release에 자체 목록을 지정할 수 있습니다. Release에 자체 카탈로그 디렉터리 지정하기를 참조하십시오.

디렉터리를 나열하는 것이 프로젝트 외부에 보관된 엔티티를 읽는 방법입니다. 나열된 디렉터리는 어디에든 있을 수 있으며 — 형제 체크아웃, 다른 프로젝트와 공유하는 디렉터리 — 그 자체가 심볼릭 링크라도 그 위치에서 읽힙니다. 그 밖의 어떤 것도 그렇게 멀리 닿지 않습니다. 프로젝트 내부에서 다른 곳으로 이어지는 링크는 따라 읽히지 않고, 경로로 프로젝트 외부 파일을 지정하는 문서는 거부되므로, 다른 곳에 보관된 엔티티는 그것을 담은 디렉터리를 나열하고 엔티티를 이름으로 지정하여 접근합니다. 프로젝트 외부에 나열된 디렉터리는 그 자체로 루트이므로, 그 아래에서 바깥으로 이어지는 링크도 읽히지 않습니다. 워크스페이스 경계에 전체 규칙이 설명되어 있습니다.

나열된 디렉터리는 디렉터리여야 합니다. 아무것도 존재하지 않거나, 파일 또는 아무 곳으로도 이어지지 않는 링크가 있는 나열된 경로는 카탈로그를 읽는 모든 명령에 의해 무엇이든 읽거나 쓰기 전에 거부됩니다. pull, 빌드, 검증, 검사, lint, 그리고 aggrega serve를 통해 편집기에서 또는 aggrega mcp를 통해 어시스턴트에서 실행되는 같은 작업도 마찬가지이므로, 나열한 것보다 적은 카탈로그를 대상으로 빌드가 실행되는 일은 없습니다. 거부 메시지는 작성된 그대로의 항목, 그것이 해석된 경로, 그것을 나열하는 구성 파일과 줄, 그리고 그것이 속한 목록을 명시합니다:

<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid

디렉터리를 만들거나 항목을 제거하십시오. 프로젝트가 나열하는 형제 체크아웃 없이 만든 프로젝트 사본은 그 항목을 제거하고, 그 체크아웃이 제공했을 내용을 레지스트리에서 해석합니다. Release 자체 항목이 나열하는 디렉터리, 파이프라인이 소유한 구성 파일이나 전역 파일이 추가하는 디렉터리, 그리고 AGGREGA_CATALOG_DIRS가 담고 있는 디렉터리도 마찬가지이며, 마지막 경우 거부 메시지는 파일 대신 이 변수를 명시합니다. 구성 자체는 계속 로드되므로 카탈로그를 읽지 않는 명령은 계속 실행됩니다. 존재하지 않는 --catalog 디렉터리는 한 명령을 위해 입력된 것이며, aggrega build는 해당 디렉터리를 명시하며 이를 거부합니다. 존재하지만 읽을 수 없는 나열된 디렉터리는 전체 카탈로그를 로드하는 명령이 이를 명시하며 거부합니다.

목록을 비워 두면 이 프로젝트에 로컬 카탈로그가 전혀 없다는 뜻이며, 이것이 catalog까지 읽히지 않게 하는 유일한 표기입니다.

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

키를 생략하는 것은 다른 의미입니다. 목록을 생략하는 것은 일반적인 경우이며, catalog는 여전히 읽힙니다.

사용한 이름에 해당하는 엔티티를 찾지 못한 빌드, pull, 검증 또는 aggrega inspect는 이 프로젝트가 로컬 엔티티를 어디서 읽는지와, 지정한 엔티티가 읽히도록 하려면 무엇을 바꿔야 하는지 알려 줍니다. 빈 목록을 작성한 경우에는 이런 안내를 하지 않습니다. 로컬 카탈로그를 읽지 않는 것이 그곳에서 선언한 내용이며, 이를 바꾸라는 제안은 사용자와 다투는 셈이기 때문입니다. 그 이름을 선언한 문서가 읽혔으나 거부된 경우에도 안내하지 않습니다. 그 문서는 이미 카탈로그가 읽는 위치에 있으므로, 보고서는 대신 문서가 위반한 내용, 즉 줄과 제약 조건을 명시하며, 문서를 옮겨도 해결되지 않습니다. 선언한 이름조차 읽을 수 없을 만큼 형식이 잘못된 문서는 사용한 이름과 대조할 수 없으므로 이 안내는 여전히 제공됩니다. 또한 그 문서가 Aggrega apiVersion을 선언하는 경우, Release의 빌드, pull 또는 검증은 그 문서가 열어야 할 파일일 수 있으므로 안내 옆에 그 문서를 파서 자체의 사유와 함께 명시합니다. 엔티티를 찾았지만 받아들일 수 없었던 실패 — 레지스트리가 lockfile이 고정한 버전으로 이제 다른 바이트를 제공하는 경우, 엔티티가 포함한 파일을 읽을 수 없는 경우 — 도 누락된 엔티티가 아니며, 자체 해결 방법만 보고합니다.

pull 또는 push가 엔티티를 고정하는지 여부

Recipe 또는 FeatureRecipe는 읽는 입력 — 전체로 작성된 원격 source:, artifacts 항목이 가져오는 파일, 옆에 있는 source:의 파일 — 에 대한 고정 값을 옆의 entity.lock에 담으며, 이를 기록하는 것은 엔티티 작성자의 단계인 aggrega pin입니다. 기본적으로 pull과 push 모두 이 단계를 실행하지 않습니다. pull은 lock이 고정하지 않은 엔티티에서 중단되고, push는 이를 게시하지 않습니다. 명령마다 하나씩 있는 두 키가 이 단계를 해당 명령의 기본 동작으로 만듭니다.

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

각 키는 자기 명령만 제어하며, 각 명령의 --pin-sources는 자기 키를 양방향으로 재정의합니다. --pin-sources=false는 고정하도록 구성된 프로젝트에서 한 번의 실행에 대해 이 단계를 끕니다. 자체 lockfile을 채우는 빌드는 pull이며 pin_sources_at_pull을 따릅니다. 이 키들은 전역 파일이 아니라 프로젝트 파일에 둡니다. 프로젝트의 pull이 고정 값을 기록하는지는 그 프로젝트의 정책이며, 프로젝트를 클론한 팀원도 같은 결과를 얻어야 합니다. pin_sources_at_pull은 다른 사람의 고정되지 않은 카탈로그를 사용하는 프로젝트가 pull할 때마다 중단되지 않고 그 고정 값을 한 번 기록하는 방법이기도 합니다.

어떤 플러그인이 capability를 렌더링하는가

Recipe는 렌더링에 사용할 capability를 지정하고(capability: helm), 그 capability를 제공하는 플러그인이 이를 렌더링합니다. 하나의 capability를 제공하는 플러그인이 정확히 하나라면 아무것도 구성할 필요가 없습니다. 둘 이상이라면 plugins.providers 항목이 플러그인의 식별자로 어느 것을 사용할지 지정합니다:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

pull은 이 항목을 해석하여 선택한 플러그인을 Release의 lockfile에 기록하고, build는 lockfile에 기록된 것을 통해 렌더링합니다. 따라서 여기서 수정한 내용은 다음 pull에서 적용됩니다.

uri는 플러그인을 게시된 위치가 아니라 항상 그 식별자 provider/<name>으로 지정합니다. aggrega plugin add provider <query> --capability <capability>는 항목을 이 형식으로, 버전 없이 작성합니다. 항목은 어느 플러그인이 capability를 제공할지를 선택하고, 버전은 Recipe가 고정한 버전이거나 그렇지 않으면 사용 가능한 가장 높은 버전이며, lockfile은 pull이 선택한 버전을 기록합니다. 컴파일러가 내장한 플러그인은 컴파일러 자신의 버전으로 제공되므로, 그런 플러그인의 항목에 작성한 버전은 그것이 바로 그 버전일 때만 해석됩니다. uri가 레지스트리 위치(oci://hub.aggrega.ai/plugin/provider/helm)인 항목은 어떤 플러그인의 식별자도 지정하지 않으며, 파일이 로드될 때 그 항목과 작성해야 할 형식을 알려 주며 거부됩니다.

항목은 프로젝트 전체에 대해 한 번 작성되지만 build는 하나의 Release에 대해 이루어지므로, 이 Release가 요청하지 않는 capability에 대한 항목도 허용되며(프로젝트의 다른 Release가 이를 읽습니다) 아무것도 보고되지 않습니다. 각 build와 각 aggrega validate --release가 검사하는 것은, Recipe가 해당 capability를 요청하는지와 관계없이 모든 항목이며, 항목이 지정하는 내용에 따라 다음과 같이 검사합니다:

  • 플러그인을 지정하는 항목에서 그 플러그인이 해당 capability를 제공하지 않으면 build가 중단되고 검증이 실패합니다. pull은 플러그인을 지정하는 모든 항목을 해석하고 해석할 수 없는 항목은 거부하므로, 항목이 한 번 pull을 거치면 build는 그 플러그인을 보유하고 무엇을 제공하는지 알게 됩니다. build가 아직 보유하지 않은 플러그인을 지정하는 항목은 pull이 그것을 가져온 후에 판단됩니다. 메시지에는 항목, 플러그인, 그 플러그인이 실제로 제공하는 것, 그리고 한 번의 수정으로 도달할 수 있는 철자가 있다면 그 철자가 표시됩니다. 이는 helm을 hlem으로 잘못 입력한 경우와 같은 오타의 형태입니다.
  • build가 읽는 어떤 플러그인도 제공하지 않는 capability만 지정하는 항목은 경고이며, build는 계속 진행됩니다. 그 capability를 제공하는 플러그인은 다른 Release만 읽는 것일 수 있어 이 build에서는 볼 수 없으며, 플러그인을 지정하지 않는 항목은 그 항목이 없어도 capability 해석이 선택했을 것 이외의 어떤 것도 선택하지 않습니다.

여기의 capability에는 콜론이 포함되지 않으며, 콜론이 포함된 것은 파일이 로드될 때 거부됩니다. Recipe의 capability:는 마지막 콜론까지를 capability로, 그 뒤를 버전 고정으로 읽으므로, helm:1.0.0을 키로 하는 항목은 결코 조회될 수 없습니다. 대신 플러그인에 버전을 고정하거나(uri: provider/helm:1.0.0) Recipe에서 고정하십시오.

어떤 importer가 소스를 초안으로 변환하는가

aggrega import는 소스의 형식을 광고하는 importer에 소스를 넘깁니다. 이는 카탈로그에 있는 importer이거나 컴파일러의 core importers 중 하나이며, Langflow 흐름의 경우 import:langflow입니다. 형식을 광고하는 importer가 정확히 하나라면 아무것도 구성할 필요가 없습니다. plugins.importer 항목은 uri에서 식별자와 버전으로 importer를 지정하여 연결하고, with 아래에 담긴 내용을 그 importer에 넘깁니다:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer는 uri를 정확히 이 형태로 작성합니다. 버전은 정확한 버전(:1.2.0)이거나 범위(:^1.2.0은 같은 메이저 버전 내에서 해당 버전 이상의 가장 높은 버전)입니다. 둘 중 하나를 작성하십시오. 이 목록에서 콜론이 없는 uri는 상대 경로가 가리키는 위치에서 설명하는 것처럼 파일 시스템 경로로 읽히며 어떤 importer도 지정하지 않습니다.

항목의 동작은 항목이 지정하는 importer가 import가 요청하는 형식을 광고하는지에 따라 달라집니다:

  • 광고하는 경우: 그 importer가 실행됩니다. 실행되는 버전은 uri가 지정하는 버전이며, 카탈로그의 다른 importer가 몇 개나 그 형식을 광고하든 관계없이 실행되고, 항목의 with.sources와 with.settings를 전달받습니다. 항목은 카탈로그가 한 형식에 대해 두 게시자의 importer를 연합하는 워크스페이스가 그중 어느 것을 사용할지 지정하는 방법입니다.
  • 광고하지 않는 경우(다른 형식의 importer, 다른 종류의 플러그인, 또는 카탈로그에 없고 컴파일러에도 포함되지 않은 것을 지정하는 경우): 항목은 그 import에 아무 역할도 하지 않습니다. 아무것도 선택하지 않으며, 그 with는 어떤 importer에도 전달되지 않습니다. 항목의 설정은 항목이 지정하는 importer에만 도달하므로, 형식마다 importer를 하나씩 연결하는 워크스페이스는 한 importer의 설정이 다른 importer에 도달하지 않도록 각각을 구성할 수 있습니다.

둘 이상의 importer가 형식을 광고하는데 그중 하나만 연결되어 있지 않은 경우(아무것도 연결되지 않았거나 항목이 그중 두 개를 지정하는 경우), import는 선택할 수 없었던 importer들을 표시하며 거부됩니다. 형식을 광고하는 importer를 지정하되 카탈로그에 있는 그 importer의 어떤 버전도 충족하지 않는 버전으로 지정하는 항목(카탈로그에 없는 정확한 버전, 또는 어떤 버전도 속하지 않는 범위)도 다른 버전을 대신 실행하지 않고 그 버전을 표시하며 거부됩니다. :latest처럼 버전이 아닌 값은 형식이 잘못된 것으로 거부됩니다. 컴파일러의 core importer 중 하나에 해당하는 Plugin 엔터티로서 카탈로그 폴더에서 옆에 모듈이 없는 것은 후보가 아닙니다. 컴파일러 자체 버전에서는 core importer가 대신 실행되며, 그 밖의 버전에서는 항목이 정확히 그 버전을 지정하거나, 실행할 수 있는 같은 이름의 importer가 그 형식을 광고하지 않는 경우에만 그 엔터티가 후보로 남습니다. 이는 직접 작성한 importer와 함께 있을 때 어느 것이 실행되는가에서 설명합니다.

각 importer는 하나의 항목으로 연결됩니다. 하나의 importer를 지정하는 두 항목(같은 식별자이며, 버전이 같든 다르든)은 어떤 명령이 구성을 읽든 구성이 로드될 때 두 항목과 그것이 작성된 파일을 표시하며 거부됩니다. 이 규칙은 목록에 기여하는 모든 파일에 걸쳐 적용됩니다. 전역 파일의 항목, 프로젝트 파일의 항목, importer_append 아래의 항목, 파이프라인의 .aggrega-config-append-ci.yaml에 있는 항목이 모두 포함되므로, importer를 새 버전으로 옮기려면 그 하나의 항목에서 버전을 변경해야 합니다. aggrega plugin add importer는 작성하는 파일의 plugins.importer 목록이 이미 그 importer를 지정하고 있을 때 바로 그렇게 합니다. 두 번째 항목을 추가하는 대신, 항목의 위치와 with를 유지한 채 그 항목을 해석한 버전으로 옮깁니다. 다른 목록은 읽지 않으므로, importer_append 아래나 파이프라인의 .aggrega-config-append-ci.yaml에 연결된 importer는 이 명령에 의해 두 번째로 연결되고, 그 쌍은 구성이 로드될 때 거부됩니다. 이런 항목은 작성된 곳에서 버전을 변경하십시오. uri가 파일 시스템 경로인 항목은 importer를 지정하지 않으므로 비교되지 않으며, plugins.governance와 plugins.linter 목록에는 이 규칙이 적용되지 않습니다. 하나의 플러그인을 이 목록에 여러 번, 매번 고유한 with와 함께 연결할 수 있습니다.

import가 사용하는 파서에는 항목이 필요하지 않습니다. importer는 소스를 읽을 때(그리고 형식을 지정하지 않은 import가 형식을 인식할 때) 소스의 구문에 맞는 파서를 사용합니다. 카탈로그가 그 구문에 대해 제공하는 파서를 사용하고, 카탈로그가 파서를 제공하지 않는 구문에 대해서는 컴파일러 자체에 포함된 파서를 사용하며, JSON도 그중 하나입니다. 따라서 카탈로그에 파서가 없는 워크스페이스도 아무것도 구성하지 않고 Langflow 또는 Flowise 흐름을 import할 수 있습니다. 파서를 연결하는 목록은 없습니다. 카탈로그가 어떤 구문에 대해 제공하는 파서가 사용되며, 이름이 다른 두 파서가 하나의 구문을 제공하면 A parse or import format is advertised by more than one plugin (파싱 또는 import 형식을 둘 이상의 플러그인이 광고함) 에서 설명하는 것처럼 거부됩니다.

아무것도 없는 상태에서 시작하기

새로 설치한 aggrega에는 두 파일이 모두 없으며, 이는 고장 난 상태가 아니라 정상적으로 작동하는 상태입니다. 모든 설정은 기본 제공 기본값으로 대체되고 명령이 실행됩니다. 빠져 있는 것은 카탈로그 콘텐츠를 pull할 레지스트리와, 어떤 서명을 수락할지 정하는 신뢰 정책이며, 이것이 바로 aggrega config init가 작성하는 내용입니다.

이를 미리 알고 있을 필요는 없습니다. 구성을 읽는 명령이 어디에서도 파일을 찾지 못하면 표준 오류에 한 번 그 사실을 알리고, 파일을 만드는 방법으로 aggrega config init를 안내합니다. 이는 실패가 아니라 안내입니다. 표준 출력은 건드리지 않고, 아무것도 묻지 않으며, 종료 상태는 명령이 원래 보고했을 값 그대로입니다. 표준 오류가 터미널일 때만 출력되므로 키보드 앞의 사용자에게만 전달되고 파이프라인 로그에 쌓이지 않습니다. 프로젝트 파일이든 전역 파일이든 어느 한 파일이 생기면 더 이상 표시되지 않습니다.

공식 허브와 그 허브가 광고하는 신뢰 정책으로 전역 파일을 초기화하려면 다음을 실행합니다:

Terminal window
aggrega config init

다른 레지스트리로 초기화하려면 --registry <host>를, 전역 파일 대신 이 프로젝트의 파일에 항목을 작성하려면 --workspace를, 아무것도 만들지 않고 작성될 내용을 확인하려면 --dry-run을 전달합니다. 명령에 대한 전체 설명은 aggrega-config.md를 참조하십시오.

레지스트리 호스트를 작성하는 방법

각 registries[].host는 레지스트리 호스트를 지정합니다. default_registry도 마찬가지이며(선택적으로 저장소 경로가 뒤따를 수 있음), 대신 그 항목 중 하나를 지정하는 경우는 예외입니다(아래 참조). 호스트는 호스트 자체로, 레지스트리의 신뢰 정책이 보관되는 단 하나의 표기로 작성합니다:

  • registry.example.com과 같이 점을 포함하는 소문자 호스트 이름
  • localhost, 또는 registry:5000과 같이 포트가 뒤따르는 단일 이름
  • 127.0.0.1과 같은 IPv4 주소, 또는 [::1]과 같이 대괄호로 묶은 IPv6 주소

각각 선택적인 :port를 붙일 수 있으며, 그 밖의 것은 허용되지 않습니다. 스킴, 경로, 자격 증명, 공백, 대문자는 모두 허용되지 않습니다. 포트가 없는 단일 이름은 레지스트리 호스트가 아닙니다. 그것은 카탈로그 엔터티 이름의 첫 번째 세그먼트(core/web-api의 core)의 형태이며, 두 가지가 서로로 읽혀서는 절대 안 되기 때문입니다.

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

표기는 정책의 일부입니다. registries 항목은 그 host:가 지정하는 호스트에 적용되고, 공식 허브의 기본 제공 서명 요구 사항은 hub.aggrega.ai에 적용되므로, 다른 방식으로 작성한 호스트는 올바른 레지스트리에 도달하더라도 그 레지스트리를 위해 작성된 정책을 놓치게 됩니다. 따라서 그런 호스트는 구성을 로드할 때 거부되며, 거부 메시지는 작성해야 할 표기를 제시합니다. HUB.AGGREGA.AI와 https://registry.example.com은 각각 hub.aggrega.ai와 registry.example.com을 제시하며 거부되고, 경로를 담지 않는 registries[].host로 쓴 registry.example.com/charts도 마찬가지입니다. 포트 443은 HTTPS로 접근하는 호스트의 기본 포트이므로 hub.aggrega.ai:443도 같은 방식으로 hub.aggrega.ai를 제시하며 거부됩니다. 반면 localhost와 그 밖의 루프백 주소는 일반 HTTP로 접근하며 443은 평범한 포트이므로, localhost:443은 작성한 그대로 허용됩니다. 빈 default_registry는 기본 레지스트리를 지정하지 않습니다.

default_registry는 저장소 경로를 포함할 수 있습니다. 많은 레지스트리는 모든 저장소를 소유자나 프로젝트 아래에 보관하며(ghcr.io/<owner>, Harbor의 <host>/<project>), 그러한 레지스트리의 기본 레지스트리는 호스트 뒤에 해당 경로를 붙여 작성합니다:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

경로는 게시와 가져오기가 이루어지는 위치입니다. 이 기본값을 통해 aggrega push는 core/api-server 버전 1.0.0을 ghcr.io/acme/component/core/api-server:1.0.0에 게시하고, core/api-server를 해석하는 pull은 같은 위치에서 이를 가져오므로, 게시할 때 첨부한 서명도 그곳에서 찾을 수 있습니다. 경로는 OCI distribution 문법의 저장소 경로입니다. 즉 소문자와 숫자로 이루어진 하나 이상의 세그먼트를 /로 연결한 것으로, 세그먼트 내부는 ., _, __ 또는 대시로 구분될 수 있으며, 태그, 다이제스트, 끝의 /는 허용되지 않습니다.

경로는 레지스트리를 신뢰하는 방식에 결코 포함되지 않습니다. 정책이 적용되는 registries 항목, aggrega login이 저장하는 자격 증명, 서명 요구 사항, 신뢰하는 ID는 모두 호스트만으로 찾으므로, 위의 ghcr.io 항목은 ghcr.io/acme와 해당 호스트의 다른 모든 경로를 관장하며, 어떤 경로 표기로도 이를 우회할 수 없습니다. 항목의 host: 자체는 경로를 담지 않습니다. 경로 앞의 호스트를 다른 표기로 쓰면 작성해야 할 위치를 제시하며 거부되고(GHCR.io/acme와 https://ghcr.io/acme는 ghcr.io/acme를 제시합니다), 호스트 뒤에 오는 것이 저장소 경로가 아니면 그 앞의 호스트를 제시하며 거부됩니다.

default_registry는 대신 항목을 지정할 수도 있습니다. registries 아래 항목의 name:으로 작성하면 해당 항목의 host:를 나타냅니다. 그러면 게시, pull, 서명 검증, 레지스트리별 모든 신뢰 설정이 그 호스트를 사용하며, 이름과 같은 표기의 호스트에서는 어떤 콘텐츠도 가져오지 않습니다:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

--registry 플래그가 이름을 일치시키는 것처럼, 이름은 호스트 표기보다 먼저 일치 여부를 확인하므로, 항목의 name:인 값은 호스트처럼 표기되어 있더라도 해당 항목을 나타냅니다. 두 항목이 같은 이름을 가지면 모호한 것으로 거부되며, 두 호스트를 모두 제시합니다. 항목은 어느 파일에 있어도 됩니다. 프로젝트의 default_registry는 전역 파일이 선언한 항목을 지정할 수 있는데, 이름은 모든 파일과 환경을 읽은 뒤 유효한 항목에 대해 한 번만 읽히기 때문입니다. 항목의 이름도 레지스트리 호스트도 아닌 값(단독이든 저장소 경로가 뒤따르든)은 거부되며, 거부 메시지는 둘 중 어느 쪽으로든 고칠 수 있다고 알려 줍니다. local/acme처럼 이름 뒤에 경로가 붙은 경우도 거부됩니다. 이름은 해당 항목의 호스트를 나타낼 뿐 그 아래의 위치를 나타내지 않으므로, 거부 메시지는 대신 작성할 두 가지 표기, 즉 local 또는 항목의 호스트 뒤에 경로를 붙인 127.0.0.1:5000/acme를 제시합니다. aggrega registry remove로 항목을 제거해도 default_registry는 작성된 그대로 남으므로, 제거된 항목을 지정하던 기본값은 이후 아무것도 지정하지 않게 되며 다시 작성할 때까지 거부됩니다.

모든 계층에 같은 표기가 적용됩니다. 값이 구성 파일에서 오든, AGGREGA_DEFAULT_REGISTRY에서 오든, aggrega push 또는 aggrega push-artifact 한 번의 대상을 지정하는 --registry 플래그에서 오든 같은 문구로 거부됩니다. 이 플래그는 호스트를 지정하며, 그것이 지시하는 게시물은 저장소 경로 없이 해당 호스트에 놓입니다. 경로는 default_registry에 속합니다. aggrega registry add와 aggrega config init --registry도 전달받은 호스트에 이 표기를 적용합니다. 이들은 그 대신 참조도 받으며, 참조가 지정하는 호스트를 키로 항목을 만듭니다. 파일에서 비롯된 거부는 파일과 키를 제시하고, 환경에서 비롯된 거부는 변수를 제시합니다. 스키마는 호스트 형태를 registries[].host에 대한 패턴으로 명시하지만 default_registry에는 명시하지 않습니다. 그 값은 어떤 항목의 이름이든 될 수 있기 때문입니다. 따라서 스키마만 읽는 편집기는 잘못 입력한 기본값을 표시하지 않으며, 이를 거부하는 것은 구성 로드입니다.

호스트는 표기만으로 판단하며, 경로도 마찬가지입니다. 이름이 해석되는지, 그곳에서 레지스트리가 응답하는지, 경로가 그 레지스트리에 존재하는지는 구성을 로드할 때 확인하지 않습니다.

무엇이 무엇을 재정의하는가

CLI flag > environment variable > configuration file > built-in default

플래그는 가장 명시적인 신호이며 무조건 우선합니다. 환경 변수는 커밋된 파일을 재정의하며, 이 덕분에 파이프라인은 추적되는 파일을 편집하지 않고도 설정을 바꿀 수 있습니다. 설정되지 않았거나 빈 문자열로 설정된 변수는 구성된 값을 비우지 않고 아래 계층으로 넘어갑니다. 두 파일 사이에서는 프로젝트 파일이 전역 파일보다 우선합니다.

플래그는 담고 있는 값이 아니라 입력되었다는 사실로 우선합니다. 참/거짓 설정에서는 이것이 쓸 수 있는 최상위 계층이 있느냐 없느냐의 차이가 됩니다. --offline은 한 번의 실행에 대해 이 모드를 켜고, --offline=false는 커밋된 파일이나 export된 변수가 켜 둔 경우 한 번의 실행에 대해 이를 끕니다. 값만 읽는 계층은 “꺼짐”과 “언급되지 않음”을 구별할 수 없으므로, 모든 명령이 플래그의 기본값을 요청한 것처럼 보이게 되고 구성된 설정을 철회할 방법이 전혀 없게 됩니다.

이것이 단일 머신의 단일 프로젝트에 대한 전체 모델입니다. 아래의 모든 내용은 이 모델을 넘어서는 프로젝트를 위해 존재합니다.

두 파일 너머

이 메커니즘들은 더 큰 형태를 위해 만들어졌습니다. 서로 관련된 프로젝트들의 모노레포, 자체 설정을 기여하는 파이프라인, 여러 프로젝트가 확장하는 공유 카탈로그 등입니다. 해당 메커니즘이 해결하는 문제가 생겼을 때 사용하십시오.

프로젝트 안의 여러 구성 파일

프로젝트 루트부터 명령이 실행되는 디렉터리까지의 모든 .aggrega-config.yaml이 기여하며, 더 가까운 파일이 더 먼 파일을 재정의합니다. 따라서 하위 프로젝트는 루트가 선언한 내용을 반복하지 않고도 이를 조정하는 자체 파일을 둘 수 있습니다.

workspace: 블록을 가진 파일만 루트를 표시합니다. 이 블록이 없는 파일도 설정을 기여하지만, 자신의 디렉터리를 프로젝트 루트로 만들지는 않습니다. 이 덕분에 하위 프로젝트의 설정 파일이 프로젝트가 시작되는 위치를 재정의하지 않습니다.

--workspace-root를 전달하면 탐색을 건너뛸 뿐 아니라 이 동작도 바뀝니다. 지정된 루트 자체의 구성 파일만 수집되므로, 그 아래 디렉터리의 파일은 기여하지 않습니다. 이렇게 하면 고정된 루트의 구성은 명령을 어디서 실행하든 동일하게 유지됩니다.

이렇게 수집되는 모든 파일은 프로젝트 내부에서 읽습니다. 프로젝트 밖으로 이어지는 심볼릭 링크인 파일, 또는 그러한 링크를 통해 도달한 디렉터리에 있는 파일은 읽지 않으며, 남은 파일로 프로젝트를 구성하는 대신 구성을 읽는 모든 명령이 해당 링크를 지목하며 중단됩니다. 아래에서 설명하는 파이프라인의 파일에도 동일하게 적용됩니다. aggrega version과 aggrega help처럼 구성을 읽지 않는 소수의 명령은 해당 링크를 지목하는 경고와 함께 실행됩니다. 편집기의 언어 서버와 어시스턴트의 도구도 같은 방식으로 구성을 읽으며, 그러한 프로젝트에서도 목록을 표시할 수 있도록 시작은 합니다. 이들의 Release 및 엔터티 목록은 아무것도 구성되지 않은 상태로 읽혀 응답하고, 읽지 않은 링크 중 하나로 해당 파일을 지목합니다. 반면 구성이 결정하는 그 밖의 모든 요청은 해당 링크를 지목하며 중단됩니다. 프로젝트 밖에 둔 구성은 전역 파일 명시적으로 지정하기에서 설명하는 대로 전역 파일로 지정하여 읽습니다. 워크스페이스 경계를 참조하십시오.

목록을 대체하지 않고 확장하기

목록 값 설정도 다른 모든 설정과 같이 동작합니다. 더 가까운 파일의 값이 더 먼 파일의 값을 대체합니다. 바깥 파일이 선언한 내용을 다시 적지 않고 추가하려면, 그 옆의 append 동반 설정을 사용하십시오.

목록 설정해당 append 동반 설정
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

동반 설정 아래의 항목은 각 계층에서 확정된 목록을 가리지 않고 그 뒤에 이어 붙여지므로, 하위 프로젝트는 루트가 이미 선언한 것에 린터를 추가할 수 있습니다.

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

한 파일이 기본 목록과 그 동반 설정을 모두 설정하면, 그 파일의 값은 기본 목록 뒤에 추가된 항목이 이어진 것입니다.

workspace: 블록은 동반 설정을 작성할 수 있는 위치의 예외입니다. 이 블록을 가진 파일은 자신의 디렉터리를 프로젝트 루트로 표시하므로, 하위 프로젝트의 파일에 workspace.catalog_dirs_append를 작성하면 바깥 프로젝트에 추가되는 대신 별도의 프로젝트가 시작됩니다. 카탈로그 디렉터리 동반 설정은 전역 파일과 프로젝트 루트 파일 사이에서 합성됩니다.

plugins.cli 목록은 자체적으로 파일 간에 합성되며 동반 설정이 없습니다. 전역 파일에 선언된 명령 확장은 모든 프로젝트에 명령을 등록하고, 프로젝트에 선언된 것은 그 프로젝트에만 등록하며, 둘 다 함께 등록됩니다. 각 항목은 플러그인 하나를 고정합니다. 즉 확인되는 uri와 aggrega plugin add cli가 검증한 바이트의 digest이며, 후자는 sha256: 뒤에 소문자 16진수 64자리로 작성합니다. 다른 표기의 다이제스트는 확인된 바이트의 해시와 결코 같을 수 없으므로, 파일을 로드할 때 해당 파일과 항목을 지목하며 거부됩니다.

Release에 자체 카탈로그 디렉터리 부여하기

프로젝트는 여러 카탈로그 변형을 나란히 둘 수 있습니다. 대상마다 하나씩, 각각 같은 Components를 서로 다른 provider용으로 렌더링하는 Recipes를 담고, 각 Release를 그중 하나에 대해 빌드합니다. 각 Release를 workspace.releases 아래에 지정하고 자체 catalog_dirs를 부여하십시오.

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

각 키는 Release 파일이며, 그것을 지정하는 구성 파일을 기준으로 상대 경로로 작성합니다. 키는 build.authoring_release와 마찬가지로 프로젝트 밖에 있는 Release를 지정할 수 있으며, 여기서 지정하는 것이 프로젝트가 그러한 Release에 도달하는 방법입니다. 워크스페이스 경계에서 설명하듯이, 프로젝트 내부에서 그곳으로 이어지는 링크는 건너뛰지 않고 읽습니다. 그 아래의 두 키는 workspace: 블록에서와 같은 의미를 가지되, 해당 Release 하나로 범위가 한정됩니다.

  • catalog_dirs는 해당 Release에 대해 워크스페이스의 목록을 대체합니다. 검색 순서, 그 뒤에 읽는 catalog 디렉터리, 빈 목록의 의미는 워크스페이스 자체 목록과 같습니다.
  • catalog_dirs_append는 Release의 목록 다음에 읽습니다. catalog_dirs_append만 작성한 항목은 워크스페이스의 목록을 유지하고 거기에 추가합니다.

맵이 지정하지 않은 Release는 워크스페이스 자체의 workspace.catalog_dirs를 읽습니다. 맵이 지정한 Release는 어떻게 빌드되든 자체 디렉터리를 읽습니다. 터미널의 aggrega build나 aggrega pull, aggrega serve를 통한 편집기, aggrega mcp를 통한 어시스턴트 모두 카탈로그를 찾기 위해 플래그가 필요하지 않습니다. 명령줄의 --catalog <dir>는 해당 호출에 한해 여전히 Release의 디렉터리보다 먼저 검색됩니다. 그리고 사용한 이름으로 엔터티를 찾지 못한 조회는, 그 엔터티를 담은 디렉터리를 나열할 위치로 해당 Release의 항목을 지목합니다.

존재하지 않는 파일을 지정한 항목은 구성을 로드할 때 해당 항목과 파일을 지목하며 거부됩니다. 따라서 Release의 이름을 바꾸면 항목의 이름도 함께 바꿀 때까지 모든 명령이 중단되며, Release가 아무런 알림 없이 워크스페이스의 목록에 대해 빌드되는 일은 없습니다. 항목이 나열하는 디렉터리는 워크스페이스의 목록이 지정하는 디렉터리와 마찬가지로 디렉터리여야 합니다. 디렉터리가 아닌 것은 해당 Release의 카탈로그를 읽는 모든 명령이 항목과 그 줄을 지목하며 거부합니다.

특정 Release와 관련 없는 작업은 여전히 워크스페이스의 목록을 읽습니다. 전체 카탈로그의 린트나 검증, 이름으로 엔터티 조회, 단독으로 검사하는 Aggregate, 편집기의 워크스페이스 엔터티 목록이 그렇습니다. AGGREGA_CATALOG_DIRS는 워크스페이스의 목록을 설정하며 여기의 어떤 항목에도 영향을 주지 않고, 파이프라인이 소유하는 구성 파일은 이 맵을 전혀 읽지 않습니다.

파이프라인이 소유하는 구성 파일

.aggrega-config-append-ci.yaml이라는 파일은 탐색이 방문하는 모든 디렉터리에서 직접 작성한 파일 옆에 둘 수 있습니다. 이 파일은 별도의 파일이므로, 자동화된 파이프라인이 사람이 작성한 내용을 건드리지 않고도 이를 소유하고 통째로 덮어쓸 수 있습니다.

이 파일은 추가만 합니다. 위의 다섯 가지 목록 설정에 대한 항목은 확정된 목록 뒤에 이어 붙여지며, 무엇도 제거하거나 스칼라를 재정의할 수 없습니다. 여기에 작성한 스칼라나 맵 키는 추가로서의 의미가 없으므로, 조용히 적용되지 않고 무시되며 경고에 표시됩니다. 또한 프로젝트 루트를 표시하지도 않으므로, 디렉터리에 이 파일을 두면 프로젝트가 시작되는 위치를 옮기지 않고 연결만 추가됩니다.

상대 경로가 가리키는 곳

상대 파일 시스템 경로는 그것을 선언한 파일의 디렉터리를 기준으로 해석됩니다. 프로젝트 루트나 명령을 실행한 디렉터리를 기준으로 하지 않습니다. 이 규칙은 두 번 읽어 둘 만합니다. 프로젝트 기준처럼 보이는 경로가 다른 곳으로 해석되어도 빌드는 의도하지 않은 내용을 대상으로 그대로 성공하기 때문입니다.

이 규칙은 workspace.catalog_dirs, workspace.releases 아래 키로 지정된 Release 파일과 각 항목이 나열하는 디렉터리, plugins.governance 또는 plugins.linter 연결의 로컬 파일 시스템 경로(디스크의 .wasm 파일을 가리키는 uri와 그 연결의 with.sources 아래 각 항목), 그리고 plugins.importer 연결의 with.sources 아래 각 항목에 적용됩니다. 세 목록 모두에서 콜론이 없고 레지스트리를 가리키지 않는 uri는 ./lint/api-rules.wasm뿐 아니라 importer/agent-flows도 이러한 경로입니다. 반면 식별자로 플러그인을 가리키는 uri는 콜론 뒤에 버전을 붙이며(importer/agent-flows:1.2.0), 작성된 그대로 유지됩니다. importer 연결의 uri는 소스를 초안으로 바꾸는 importer에서 설명하듯 연결하는 importer를 가리키며, 가져오기는 그곳에 작성된 경로에서 모듈을 읽지 않습니다. 이 규칙은 append 짝 설정 아래의 항목에도 적용되며, 각 항목은 병합이 끝나는 파일이 아니라 자신을 선언한 파일을 기준으로 합니다. 또한 mcp.tls.cert_file, mcp.tls.key_file, mcp.authorization.jwks_file에도 적용되므로, 이를 지정한 파일 옆에 있는 파일은 서버를 어디서 실행하든 찾을 수 있습니다.

따라서 다음과 같은 구조에서:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

루트 파일에 ./catalog를 작성하면 이 경로는 myproject/catalog를 가리킵니다. services/.aggrega-config.yaml에 작성하면 같은 텍스트가 myproject/services/catalog를 가리킵니다. 절대 경로는 작성된 그대로 유지되며, oci://hub.aggrega.ai/plugins/helm:1.0.0 같은 레지스트리 참조도 마찬가지입니다.

다음 설정은 기준으로 삼을 선언 파일이 없거나 이를 읽는 모든 곳이 다른 기준으로 해석하기 때문에 의도적으로 이 규칙을 따르지 않습니다:

  • artifact_cache_dir는 명령을 어디서 실행하든 프로젝트 루트를 기준으로 해석되므로, 캐시는 실행 위치마다 하나가 아니라 단일 디렉터리가 됩니다. 절대 값은 구성을 불러올 때 거부됩니다.
  • AGGREGA_CATALOG_DIRS는 환경에서 오며 선언 파일이 전혀 없으므로, 절대 경로를 지정하십시오.
  • mcp.listen은 작성된 그대로 사용되며, unix:<path> 형식의 파일 시스템 경로도 마찬가지입니다. 같은 주소는 선언 파일이 없는 aggrega mcp --listen에서도 전달되므로, 구성된 표기만 기준 디렉터리에 고정하면 하나의 문자열이 출처에 따라 서로 다른 두 위치를 가리키게 됩니다. 소켓에는 절대 경로를 지정하십시오.

저장소가 공유되는 하나의 설정

거의 모든 설정은 작업 중인 프로젝트에 속한 것을 제어합니다. 카탈로그 내용을 어떤 디렉터리를 통해 해석하는지, 어떤 플러그인이 대상을 렌더링하는지, 내용을 얼마나 엄격하게 판단하는지, 데몬의 메모리 내 캐시가 얼마나 커질 수 있는지 등입니다. 프로젝트 파일의 값은 그 프로젝트 자체의 대상을 제어하므로 주의할 점이 없습니다.

compiled_module_cache.max_bytes는 유일한 예외입니다. 이 설정이 제한하는 대상이 프로젝트별이 아니기 때문입니다. 컴파일된 플러그인 코드는 컴퓨터의 모든 프로젝트가 재사용하는 단일 디렉터리에 보관되므로, 특정 플러그인은 프로젝트마다가 아니라 한 번만 컴파일됩니다. 상한 자체는 다른 설정과 마찬가지로 해석되지만(프로젝트 파일에 작성하면 그 프로젝트에서는 그 값이 우선합니다) 저장소의 크기는 하나뿐이며, 적용되는 크기는 가장 최근 빌드의 것입니다. 상한을 서로 다르게 지정한 두 프로젝트는 번갈아 적용되며, 더 낮은 상한은 다른 프로젝트가 비용을 들여 컴파일한 코드를 폐기합니다.

따라서 빌드하는 모든 것에 하나의 값을 원한다면 전역 파일에 두고, 단일 빌드가 컴파일하는 양보다 크게 유지하십시오. aggrega cache status는 저장소가 현재 보유한 내용을 보고하며, aggrega config show --origin은 현재 적용 중인 상한이 실제로 어느 파일에서 왔는지 알려 줍니다.

다른 사람이 접근하는 서버를 위한 설정

aggrega mcp는 Model Context Protocol을 사용합니다. 자신의 컴퓨터에서는 클라이언트가 이를 하위 프로세스로 실행하고 표준 입력과 출력으로 통신하며, 이것이 기본값입니다. 이 형태에서 읽는 설정은 기본값으로 둔 mcp.transport와 mcp.announce_tools뿐입니다. mcp 블록의 나머지는 mcp.transport: http로 선택하는 다른 형태를 위한 것입니다. 즉 호스트에서 오래 실행되는 하나의 프로세스로, 그 키보드 앞에 있지 않은 호출자가 HTTP로 접근합니다.

# <project>/.aggrega-config.yaml
mcp:
transport: http
listen: 127.0.0.1:7777
authorization:
issuer: https://login.example.com
resource: https://mcp.example.com/mcp
allowed_origins:
- https://studio.example.com
limits:
max_concurrent_requests: 32
deny_reach:
- registry
announce_tools:
- list-entities
- get-schema
- validate
- build
health:
listen: 127.0.0.1:7778

전송 방식을 선택하는 것은 mcp.transport입니다. http는 리스너를 시작하고, 기본값인 stdio는 표준 입력과 출력으로 통신하며 이는 하위 프로세스 클라이언트가 기대하는 방식입니다. 그 밖의 값은 이 파일을 불러올 때 거부됩니다. aggrega mcp --transport <stdio|http>는 한 번의 실행에 대해 같은 일을 하며, 모든 플래그가 모든 파일보다 우선하듯 이 키보다 우선합니다.

mcp.listen은 리스너가 바인딩할 위치를 지정할 뿐, 아무것도 선택하지 않습니다. host:port 주소나 unix:<path> 소켓을 지정하십시오. aggrega mcp --listen <address>는 한 번의 실행에 대해 이보다 우선합니다. http가 선택되었는데 어느 쪽에서도 주소가 없으면 무엇이든 바인딩하기 전에 실행이 거부됩니다. stdio가 선택된 경우 직접 입력한 --listen은 거부되고, 이 키만 지정한 주소는 사용되지 않은 채 남습니다. 서버는 오류 스트림에 이 파일과 mcp.transport: http를 언급하는 한 줄로 이를 알립니다. 따라서 다른 사람이 접근하는 서버는 위와 같이 두 키를 모두 설정하며, 그 파일이 적용되는 디렉터리에서 실행된 클라이언트는 여전히 자체 스트림으로 서버에 접근합니다. unix: 경로는 기준 디렉터리에 고정되지 않고 작성된 그대로 사용됩니다. 상대 경로가 가리키는 곳을 참조하십시오.

mcp.tls.cert_file과 mcp.tls.key_file은 프로세스에 TLS를 적용합니다. 둘 다 설정하면 리스너가 직접 HTTPS를 제공합니다. 둘 다 생략하면 평문으로 제공하며, 이는 루프백이나 Unix 소켓에서만 허용됩니다. 앞단의 프록시가 인증서를 보유하고 프로세스로 전달할 때 사용하는 형태입니다. 그 밖의 주소에서 평문 리스너는 무엇이든 바인딩하기 전에 이 두 키를 언급하며 거부되고, 둘 중 하나만 설정한 경우도 마찬가지입니다. 둘 다 파일 시스템 경로이며 위의 규칙을 따릅니다. 상대 경로는 이를 선언한 파일의 디렉터리를 기준으로 해석되므로, 그 파일 옆에 커밋된 인증서는 서버를 어디서 실행하든 찾을 수 있습니다. 인증서를 프로젝트 외부에서 관리하는 경우에는 절대 경로로 작성하십시오.

mcp.authorization.issuer와 mcp.authorization.resource는 호출자가 제시하는 토큰을 누가 발급하는지, 그리고 토큰이 발급되는 대상 리소스로서 이 서버를 무엇이라 부르는지를 지정합니다. http 전송이 선택될 때마다 두 키 모두 필수이며, 이 둘이 없으면 아무것도 바인딩하기 전에 리스너가 거부됩니다. 엔드포인트에 대한 모든 요청에는 bearer 토큰 챌린지로 응답하는데, 갈 곳을 지정하지 않는 챌린지에는 클라이언트가 대응할 수 없기 때문입니다. 스킴과 호스트를 포함한 전체 주소를 작성합니다. issuer는 해당 인가 서버가 밝히는 자체 식별자와 정확히 같게, resource는 호출자가 실제로 도달하는 주소로 작성합니다. 앞단에 프록시가 있다면 이 프로세스가 바인딩하는 주소가 아니라 그 프록시가 제시하는 호스트입니다. 두 값은 리스너가 제공하는 OAuth protected-resource 메타데이터 문서에 자격 증명 요구 없이 공개되며, 클라이언트는 이 문서를 보고 토큰을 어디서 얻을지 알아냅니다. 어느 쪽도 비밀을 담지 않습니다. 토큰은 그것을 제시하는 요청에 실려 오며 구성 파일에 기록되지 않습니다. 인가 서버가 이 머신(localhost, 127.0.0.1 또는 ::1)에서 실행되지 않는 한 issuer는 https 주소여야 하며, 다른 호스트의 일반 http issuer를 지정한 리스너는 키와 호출자를 어떤 방식으로 읽든 아무것도 바인딩하기 전에 거부됩니다. 모든 클라이언트는 토큰을 얻기 위해 issuer로 보내지므로, 일반 http에서는 인가 코드와 토큰이 보호 없이 네트워크를 건너게 되고, 키도 그곳에서 읽는다면 그 경로에 있는 누구든 키를 바꿔치기할 수 있기 때문입니다.

mcp.authorization.jwks_file은 토큰 검증에 사용할 키를 담은 파일을 지정하며, 인가 서버에서 키를 읽는 대신 사용됩니다. 생략하면 서버는 해당 인가 서버의 메타데이터를 well-known 주소에서 읽고 그곳에 공개된 jwks_uri를 따르며, 네트워크에 접근할 수 있는 워크스페이스는 이렇게 동작합니다. 이 키 주소에도 issuer와 같은 규칙이 적용되며, 두 읽기 중 어느 쪽이 리디렉션되는 주소에도 마찬가지입니다. 다른 호스트의 일반 http 주소에는 요청하지 않으며, 그 키가 필요한 토큰에는 인가 서버가 메타데이터와 키를 https로 공개할 때까지 503으로 응답합니다. 설정하면 인가 서버에 전혀 연결하지 않습니다. offline: true를 선언한 워크스페이스에는 이것이 필요하며, 그런 워크스페이스는 이 키가 파일을 지정하지 않으면 리스너가 바인딩하기 전에 거부됩니다. 이 값은 경로이며 위의 규칙을 따릅니다. 상대 경로는 그것을 선언한 파일의 디렉터리를 기준으로 해석되므로, 그 파일 옆에 커밋된 키 세트는 서버를 어디서 실행하든 찾을 수 있습니다. 이 파일에는 인가 서버가 공개하는 공개 검증 키가 들어 있으며, 서명하는 것도 비밀도 들어 있지 않습니다.

mcp.allowed_origins는 요청에 Origin 헤더가 있을 때만 참조되며, 이는 실제로는 브라우저가 요청을 보냈다는 뜻입니다. 제공하는 오리진을 여기에 나열합니다. 나열되지 않은 오리진을 지정한 요청은 거부되고, 이 헤더가 없는 요청은 상관없이 처리됩니다. 브라우저가 아닌 클라이언트는 이 헤더를 보내지 않으므로 항목이 필요 없습니다. 항목은 헤더와 정확히 비교되므로 브라우저가 보내는 형태로 작성합니다. 소문자 스킴, ://, 소문자 호스트, 그리고 포트가 스킴의 기본값이 아닐 때만 :와 포트를 붙이며(https://studio.example.com, 또는 자신의 머신에서 제공하는 페이지라면 http://localhost:3000), 경로와 끝의 /는 없습니다. 다른 형태의 항목은 결코 일치할 수 없으므로 이 파일을 로드할 때 해당 항목을 지정하며 거부됩니다.

mcp.limits는 한 호출자가 요청할 수 있는 범위를 제한합니다. 단일 요청 본문의 최대 크기, 동시에 실행되는 요청 수, 한 호출자가 1분에 보낼 수 있는 요청 수입니다. 세 가지 모두 항상 적용되며, 제한을 해제하는 값은 없습니다. 세 번째인 requests_per_minute는 호출자별로 따로 계산되므로, 한 호출자가 요청을 많이 보내도 다른 호출자에게는 영향이 없습니다.

mcp.authorization.trusted_proxy는 여기서 토큰을 확인하는 대신 앞단 프록시로부터 호출자를 읽습니다. principal_header를 그 프록시가 호출자가 누구인지 알리는 헤더로 설정하고, 선택적으로 scopes_header를 호출자의 스코프를 담는 헤더로 설정합니다. 둘 다 X-Forwarded-User 같은 HTTP 헤더 이름입니다. 문자, 숫자, 하이픈 및 헤더 이름에 쓸 수 있는 몇 가지 다른 문자로 구성되며 공백이나 콜론은 없습니다. 다른 형태의 이름은 어떤 요청에도 실릴 수 없으므로 이 파일을 로드할 때 해당 키를 지정하며 거부됩니다. 이 모드에서는 토큰을 전혀 읽지 않으며, principal 헤더가 없는 요청은 거부됩니다. 이때는 헤더가 자격 증명의 전부이므로 다른 누구도 그것을 설정할 수 없는 곳에서만 신뢰할 수 있습니다. 따라서 mcp.listen이 루프백이나 Unix 소켓이 아니면 프로세스가 바인딩하기 전에 거부됩니다. 블록을 생략하면 기본값대로 이 서버가 직접 토큰을 확인합니다. principal_header가 비어 있는 블록은 그 기본값으로 읽히지 않고 거부됩니다.

mcp.deny_reach는 이 배포에서 특정 종류의 도달 범위를 회수합니다. 서버가 수행하는 모든 작업은 자신의 효과가 어디까지 미치는지 선언합니다. 읽거나 렌더링하고 아무것도 남기지 않는 작업은 none, 이 프로세스가 제공하는 워크스페이스 안에 쓰는 작업은 workspace, 게시·서명·철회하는 작업은 registry, 호스트의 모든 워크스페이스가 공유하는 것을 바꾸는 작업은 machine입니다. 여기에 종류를 지정하면 그 종류에 도달하는 모든 도구가 회수됩니다. 해당 도구는 호출자의 토큰에 무엇이 있든 모든 호출자의 도구 목록에서 빠지며, 그 도구를 호출하면 이 설정을 지정하며 거부됩니다. 따라서 이것은 호출자가 아닌 배포의 제한이며 어떤 자격 증명으로도 해제할 수 없습니다. 읽기만 제공하려는 서버는 쓰기 종류 세 가지를 여기에 나열하며, 그러면 모든 스코프를 가진 토큰의 호출자에게도 게시할 수 없습니다. 기본값대로 생략하면 이 배포는 호출자의 스코프가 허용하는 모든 것을 제공합니다. 네 가지 중 하나가 아닌 값은 무시되지 않고 이 파일을 로드할 때 거부됩니다. 이 설정과 관계없이 machine 종류는 HTTP로 제공되지 않으므로, 이를 지정하는 것은 허용되지만 아무것도 바꾸지 않습니다. 종류와 그것을 허용하는 스코프는 aggrega-mcp.md에 설명되어 있습니다.

mcp.announce_tools는 서버가 알리는 도구를 좁히며, 위의 키와는 다른 제한입니다. 이 서버가 알릴 도구를 도구 목록이 보고하는 철자대로 지정하면 정확히 그 도구들만 알려집니다. 빠진 도구는 모든 호출자의 도구 목록에 나타나지 않으며, 그래도 이름으로 호출하면 이 설정을 지정하며 거부됩니다. 키를 생략하면(기본값) 서버가 제공하는 모든 도구가 알려지고, 빈 목록을 작성하면 아무것도 알려지지 않습니다. 따라서 두 표기는 서로 다른 의미이며 기본값이 대신 채워지지 않습니다. deny_reach와의 차이는 각각이 무엇을 빼는가에 있습니다. deny_reach는 기능을 뺍니다. 회수된 종류의 작업은 이곳에서 전혀 제공되지 않으며 어떤 자격 증명으로도 되돌릴 수 없습니다. announce_tools는 알림만 뺍니다. 빠진 도구는 서버가 여전히 가진 기능이며, 이것이 대응하는 대상은 등록할 도구 수를 제한하는 클라이언트로, 때로는 연결된 모든 서버에 걸쳐 한꺼번에 제한합니다. 둘 다 설정되면 회수가 우선하므로, 회수된 종류의 도구는 이 키가 어떻게 지정하든 계속 나타나지 않습니다. 어떤 도구에도 해당하지 않는 이름이 있으면, 요청한 것보다 좁은 표면을 남기는 대신 서버가 무엇이든 제공하기 전에 멈추고 실제로 가진 도구를 나열합니다. http 전송이 시작하는 리스너를 구성하는 여기의 다른 키들과 달리, 이 키는 서버가 어떤 전송을 사용하든 읽힙니다. 좁히기가 필요한 클라이언트는 대개 자체 표준 입력과 출력으로 프로세스를 실행한 클라이언트이기 때문입니다. 나머지는 aggrega-mcp.md에 설명되어 있습니다.

mcp.health.listen은 활성 상태 및 준비 상태 검사를 별도의 주소에 둡니다. mcp.listen의 두 가지 형식 중 하나로 주소를 지정하면 두 번째 리스너가 그 주소에서 GET /healthz에 응답하고 — 프로세스가 실행되는 순간부터 200 — GET /readyz에 응답합니다 — 워크스페이스가 해석되고 엔드포인트가 바인딩될 때까지는 503, 그 이후로는 200이며, 이를 통해 로드 밸런서는 프로세스가 실제로 호출에 응답할 수 있을 때까지 트래픽을 보류할 수 있습니다. 이 키를 생략하면 두 검사 모두 어디에서도 응답하지 않습니다. mcp.listen이 지정하는 주소에서는 두 검사에 절대 응답하지 않으며, 그 주소는 제공하지 않는 모든 경로와 마찬가지로 이들에게 404를 반환합니다. 그곳에서의 프로브는 다른 모든 요청을 거부하는 리스너를 인증 없이 읽는 것이 되기 때문입니다. mcp.listen과 달리 이 주소는 제한되지 않으며 어떤 주소도 거부되지 않습니다. 이 프로세스 옆의 감독 프로세스가 접근하는 루프백이나 Unix 소켓을 지정하고, 선택한 주소에 접근할 수 있는 누구든 이 두 응답을 읽을 수 있다는 점에 유의하십시오.

schema/other/aggrega-config.md에는 이 각 키와 함께 기본값이 있는 경우 그 기본값이 나와 있습니다.

프로젝트 루트를 인식하는 다른 방법

--workspace-root <path> 또는 이에 대응하는 AGGREGA_WORKSPACE_ROOT는 루트를 직접 지정하며 탐색을 건너뜁니다. 지정한 폴더는 존재해야 합니다. 아무것도 가리키지 않거나 파일을 가리키는 경로는 명령이 다른 작업을 하기 전에 거부되며, 거부 메시지는 둘 중 값을 제공한 쪽을 지목하고 주어진 값을 그대로 인용합니다. 그렇지 않으면 탐색은 작업 디렉터리에서 위쪽으로 올라가며, 앵커의 종류는 가까운 정도가 아니라 서로 간의 순위로 비교됩니다.

  • workspace: 블록을 가진 .aggrega-config.yaml이 무조건 우선합니다. 어느 깊이에 있든 마찬가지입니다. 탐색은 아래에 설명된 종류의 마커를 지나친 후에도 이를 찾기 위해 계속 올라가므로, 위쪽에 명시적으로 표시된 루트는 항상 그 아래의 부수적인 마커보다 우선합니다.
  • 그것이 없으면 다음 마커 중 가장 가까운 것이 루트를 정하며, 한 디렉터리 안에서는 다음 순서로 순위가 매겨집니다. .aggrega/ 디렉터리, 그다음 aggregate*.yaml, 그다음 release*.yaml, 그다음 manifest*.yaml.
  • 모두 해당하지 않으면 작업 디렉터리가 사용됩니다 — 명령은 시작을 거부하지 않고 실행됩니다. 결과가 워크스페이스에 따라 달라지는 명령, 즉 워크스페이스의 문서를 읽거나 쓰고, 아티팩트 캐시를 읽거나 채우거나, 워크스페이스를 제공하는 명령은 표준 오류에 한 번 경고합니다: warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. 결과가 어느 폴더가 루트인지에 따라 달라지지 않는 명령은 구성을 읽는 경우에도 아무것도 출력하지 않습니다. aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain, aggrega login이 그러한 명령에 속합니다. 워크스페이스 자체의 구성 파일을 쓰는 것이 작업인 aggrega config capture는 그런 폴더에서는 아무것도 쓰지 않고 그렇다는 오류와 함께 종료합니다.

그러한 폴더에서는 아티팩트 캐시에 아무것도 기록되지 않습니다. .aggrega/ 디렉터리 자체가 위의 마커 중 하나이므로, 그곳에 캐시를 기록하면 한때 무언가를 가져왔다는 이유만으로 그 폴더가 워크스페이스가 되어 버립니다. 작업 중에 캐시를 채우는 명령 — aggrega pull, 먼저 의존성을 해석하는 빌드, aggrega registry update, 레지스트리에서 명령 확장 플러그인을 추가하는 작업 — 은 무언가를 가져오기 전에 거부되며, 그 폴더와 두 가지 해결 방법을 알려 줍니다. --workspace-root 또는 AGGREGA_WORKSPACE_ROOT로 워크스페이스를 지정하거나, 폴더에 workspace: 블록을 가진 .aggrega-config.yaml을 두는 것입니다. aggrega pin과, 옆에 있는 entity.lock이 기록한 핀을 따르는 Recipe 또는 FeatureRecipe의 aggrega push는 엔터티가 전체를 명시한 원격 소스, 즉 엔터티를 고정하거나 그 핀을 비교할 때 가져오는 소스로만 캐시를 채웁니다. 이들 명령은 그러한 소스를 가져오게 되는 경우, 가져오기 전에 같은 방식으로 거부됩니다. 그러한 소스가 없는 엔터티 — 소스가 전혀 없거나, 로컬 소스이거나, 각 Release가 좌표를 채우는 소스인 경우 — 는 다른 곳에서와 마찬가지로 그곳에서도 고정되거나 게시됩니다. 그곳에서의 빌드는 거부되지 않지만, lockfile이 고정하고 캐시에 더 이상 없는 외부 입력은 이를 복구하기 위해 다시 가져오지 않습니다. 렌더링에는 오프라인 상태의 문장이 전달되는 것과 같은 방식으로 해당 입력 대신 같은 문장이 전달되며, 렌더링은 이를 보고합니다. artifact_cache_dir이 캐시를 어디에 두든 여기서는 아무것도 달라지지 않습니다. 그 디렉터리는 발견된 루트에 결합되기 때문입니다. 읽기만 하는 명령은 여전히 응답합니다.

이 마지막 대체 동작에는 한 가지 예외가 있습니다. 아무것도 루트를 지정하지 않았고 작업 디렉터리도 아무것도 정하지 않을 때, 하나의 Release나 하나의 엔터티 문서에 관한 명령이 그 파일을 절대 경로로 지정하면, 파일이 있는 폴더에서 위쪽으로 올라가며 루트를 다시 탐색하고 찾은 것을 사용합니다. 즉 파일이 속한 워크스페이스를, 아무것도 없으면 그 폴더를 사용합니다. 해당 파일은 aggrega build와 aggrega pull에서 --release가 지정하는 파일, aggrega validate, aggrega lint, aggrega inspect에 주어진 Release 또는 주어진 파일, 그리고 aggrega pin, aggrega push, aggrega edit-document에 주어진 문서입니다. 따라서 프로젝트 외부에서 빌드한 프로젝트의 Release는 명령이 프로젝트 내부에서 실행될 때와 마찬가지로 프로젝트 자체의 구성을 읽으며, 명령이 출력하는 구성 경고는 그 워크스페이스의 것입니다. 파일이 있는 폴더도 아무것도 정하지 않으면, 그 폴더가 명령의 알림이 가리키는 폴더이자 캐시가 기록되지 않는 폴더가 됩니다. 상대 경로는 명령을 실행한 디렉터리를 기준으로 읽히며 아무것도 바꾸지 않고, 지정된 루트나 그 자체로 워크스페이스 안에 있는 작업 디렉터리는 그대로 사용됩니다. 어시스턴트 서버는 Release나 문서를 절대 경로로 지정하는 호출에 같은 규칙을 적용합니다.

workspace: 블록으로 루트를 표시하는 것이 명시적인 선택이며 권장되는 방법입니다. 파일 및 디렉터리 마커는 루트를 선언하지 않은 프로젝트도 빌드할 수 있게 해 줍니다.

전역 파일을 명시적으로 지정하기

전역 계층은 다음 순서로 해석됩니다.

  1. --config <path>: 호출별 형식입니다.
  2. AGGREGA_CONFIG 환경 변수입니다.
  3. 기본 위치: Windows에서는 APPDATA 환경 변수가 가리키는 디렉터리 안의 aggrega\config.yaml, 그 외에서는 XDG_CONFIG_HOME이 가리키는 디렉터리 안의 aggrega/config.yaml이며, 없으면 ~/.config/aggrega/config.yaml로 대체됩니다.

처음 두 가지는 명시적인 파일을 지정하므로, 존재하지 않는 경로는 조용히 대체되지 않고 명확한 오류가 됩니다. 특정 파일을 요청했기 때문입니다. 구성을 읽는 명령은 경로로 끝나는 한 문장을 출력하고 중지하므로 경로를 복사할 수 있습니다. aggrega config init은 예외입니다. 그 파일을 만드는 것이 이 명령의 목적이기 때문에, 지정된 파일을 만들고 그 사실을 알립니다. 기본 위치는 파일이 있으면 로드되고, 없으면 조용히 건너뜁니다. 어느 파일로 해석되든 프로젝트의 파일은 여전히 그 위에 계층으로 쌓입니다.

이 중 어느 것도 해석되지 않으면 — 지정된 파일이 없고 기본 위치를 읽는 데 쓰이는 변수도 설정되지 않은 경우 — 전역 파일에 기록하는 명령은 중지하고 무엇을 설정해야 하는지 알려 줍니다. 환경 변수에는 플랫폼별로 각 위치를 읽는 데 쓰이는 변수가 나와 있습니다.

이 선택은 구성을 기록하는 명령이 어디에 기록할지도 결정합니다. --config <path>로 실행한 명령은 그 파일에서 구성을 읽고 같은 파일에 변경 사항을 적용하므로, 한 명령이 기록한 내용을 다음 명령이 다시 읽습니다.

명령이 기본적으로 두 파일 중 어디에 기록하는지는 설정의 성격에 따라 결정됩니다. 레지스트리와 같은 머신 전체 도구 설정은 전역 파일로 가고, provider 바인딩이나 소켓 연결처럼 빌드에 참여하는 설정은 프로젝트의 커밋된 파일로 가서 프로젝트와 함께 이동합니다. 이를 재정의하려면 --global 또는 --workspace를 전달하십시오. 명령은 기록한 파일을 출력합니다.

참고 항목

  • aggrega-config.md — 구성을 초기화하고, 검사하고, 고정하는 aggrega config 명령.
  • environment-variables.md — AGGREGA_ 접두사가 붙은 모든 변수와 시크릿을 제공하는 위치.
  • global-flags.md — --config, --workspace-root, 그리고 모든 하위 명령이 받는 그 밖의 플래그.
  • schema/other/aggrega-config.md — 모든 구성 키와 그 타입 및 기본값.
  • aggrega-cache.md — artifact_cache_dir에 실제로 담기는 내용.
  • workspace-boundary.md — 워크스페이스 안에 머무는 경로와, 이 구성이 지정하는 디렉터리와 파일이 워크스페이스 밖에 닿는 방식.
  • aggrega-mcp.md — mcp 블록이 구성하는 서버.