aggrega build
aggrega build는 Aggregate + Release 쌍을 provider 고유의 산출물(Helm 매니페스트, 재배포 가능한 Helm 차트, docker-compose YAML)로 컴파일하며, 출력에서 설명하는 대로 워크스페이스 루트의 dist/ 아래에 생성합니다. Release가 단일 진입점입니다. Release는 Aggregate와 Manifest를 지정하고, 경계를 선언하며, 컴포넌트를 provider로 라우팅합니다.
공통 플래그
다음 두 플래그는 아래 플래그 레퍼런스만으로는 전달할 수 없는 동작을 가집니다.
--catalog <dir>— 카탈로그 엔터티, 즉 Component, Feature, Recipe, FeatureRecipe 작성 종류와 라이브러리 종류, Aggregates, Plugins를 담은 디렉터리로, 재귀적으로 로드됩니다. 각--catalog디렉터리는 구성된 디렉터리보다 먼저, 지정된 순서대로 검색됩니다. 프로젝트 로컬 카탈로그를 공유 카탈로그와 함께 검색하려면 둘 다 전달하거나(--catalog ./catalog --catalog ../shared-catalog)catalog_dirs아래에 나열합니다.--detail을 지정하면 우선순위가 더 높은 디렉터리에 의해 가려진 엔터티가 다른 빌드 경고와 함께 stderr에 보고됩니다. 존재하지 않는--catalog디렉터리는 해당 디렉터리를 지명하며 빌드를 중단합니다.catalog_dirs아래에 나열되었지만 실제로는 디렉터리가 아닌 디렉터리도 마찬가지로, 무엇이든 읽거나 쓰기 전에 빌드를 중단하며 해당 항목과 그 항목을 나열한 구성 파일 및 줄을 지명합니다. 로컬 엔터티를 읽어 오는 위치를 참고하십시오. 참조가 아무것으로도 해석되지 않아 중단되는 빌드는 중단 메시지 아래의 참고 사항에서, 로드 시 건너뛴 카탈로그 파일 가운데 그 디렉터리들에서 Aggrega apiVersion을 선언하지만(들여쓰기 없이apiVersion:으로 시작하고 값이aggrega.ai/로 시작하는 줄) 로드할 수 없었던 각 파일, 예컨대 YAML로 구문 분석되지 않는 파일을 파서 자체의 사유와 함께 지명합니다. 다른 apiVersion을 선언하거나 아무것도 선언하지 않은 YAML 파일은 Aggrega 문서가 아니므로 그곳에 지명되지 않습니다.--detail— pull 단계가 수행한 작업을 보고합니다. 이는aggrega pull --detail이 내보내는 것과 동일한 일시적 pull 이벤트 진단입니다. 보고할 내용이 있는지를 결정하는 것은 lockfile이 이미 있는지가 아니라--auto-pull로 또는auto_pull을 활성화하여 pull 단계를 요청했는지입니다. 요청된 pull 단계는 어느 경우든 실행되어, 없는 lockfile을 채우고 기존 lockfile의 고정값을 따릅니다. pull 단계가 실행되지 않으면 이 플래그는 stdout에 한 줄짜리 안내를 출력하고 계속 진행합니다. 커밋된 lockfile에 없는 해석 계층을 지어내는 일은 결코 없습니다. Release 의존성의 pull 이후 해석 상태를 확인하려면aggrega inspect를 사용하십시오.
--dry-run은 아래 쓰지 않고 빌드 미리 보기에서, --trace와 --trace-unredacted는 트레이스 출력과 보류된 값 표시에서 다룹니다.
빌드의 일부로 lockfile 채우기
빌드는 기본적으로 의존성에 대해 읽기 전용입니다. 즉, lockfile이 필요하지만 lockfile을 쓰지는 않습니다. --auto-pull과 auto_pull 워크스페이스 설정은 빌드에 pull 단계를 추가하므로, 명령 하나로 Release의 의존성을 해석하고 해석한 결과를 기준으로 컴파일합니다.
Release를 편집하면 lockfile이 이를 감지합니다. lockfile은 Release와 그것이 확장하는 각 Release를 내용의 다이제스트로 기록합니다. 따라서 pull 이후 편집된 Release에 대한 읽기 전용 빌드는 아무것도 렌더링하기 전에 중단되며, 해당 파일을 지목하고 aggrega pull --release <release>를 실행하라고 안내합니다. 이 명령은 다른 모든 고정을 유지하면서 편집 내용을 기록합니다. 다이제스트는 바이트를 있는 그대로 다루므로 주석이나 공백 변경도 편집으로 간주됩니다. 자동 pull 빌드는 그 pull 단계를 직접 실행하므로 편집 내용을 기록하고 빌드합니다.
Release는 한 번만 렌더링됩니다. Release가 어떤 외부 입력을 소비하는지는 문서가 선언하는 내용이 아니라 렌더링 결과로 정해지므로, pull 단계는 이를 알아내기 위해 Release를 렌더링하며 그 렌더링이 곧 빌드의 렌더링입니다. 따라서 자동 pull 빌드의 비용은 렌더링 한 번으로, 이미 lockfile이 있는 상태에서 실행하는 일반 빌드와 같습니다.
렌더링에 영향을 주는 플래그는 그 렌더링에 적용됩니다. --trace, --verify-determinism, --disable-plugin-cache, --no-unsupported-field-warnings는 일반 빌드의 렌더링에 적용되는 것과 같은 조건으로 자동 pull 빌드가 수행하는 렌더링에 적용되므로, 단일 명령 빌드에서 트레이스나 결정성 검사를 요청하면 그대로 얻을 수 있습니다. --dry-run은 예외이며, 조용히 무시되는 것이 아니라 거부됩니다. dry run은 아무것도 쓰지 않지만 pull 단계는 쓰기를 하므로, 이 조합은 어떤 작업도 하기 전에 중단됩니다(쓰지 않고 빌드 미리 보기 참조).
빌드가 lockfile이 고정한 내용을 읽는 방식
lockfile의 고정(pin)은 위치가 아니라 내용, 즉 다이제스트를 가리킵니다. 엔터티의 경우 이는 해당 엔터티의 게시본이 담고 있는 것, 곧 그 문서와 문서가 지정하는 파일들의 다이제스트입니다. 따라서 The lockfile에서 설명하듯, 엔터티의 카탈로그 디렉터리 사본과 그 게시본을 담은 캐시 항목은 같은 고정 값을 가집니다. 빌드는 고정된 각 의존성을 이미 머신에 있는 소스에서 읽습니다. 다른 모든 곳과 마찬가지로 먼저 카탈로그 디렉터리를 읽고, 그다음 .aggrega/cache 아래의 콘텐츠 캐시를 읽습니다. 이를 읽을 때는 어떤 레지스트리에도 요청하지 않으며, 빌드가 pull 단계를 실행하는 경우 그 pull 단계만 가져오기를 수행합니다.
더 이상 고정 값을 담고 있지 않은 캐시 항목은 건너뜁니다. 제자리에서 편집된 엔터티, 즉 같은 version 아래의 새 본문은 콘텐츠 캐시에 해당 이름과 버전으로 이전 본문을 남겨 둡니다. 카탈로그 디렉터리에 내용의 다이제스트가 고정 값과 일치하는 사본이 있으면, 빌드는 그 사본을 읽고 캐시 항목은 전혀 읽지 않으며, 표준 오류에 그 사실을 출력하면서 해당 항목과 두 다이제스트를 함께 표시합니다.
reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes어떤 카탈로그 디렉터리에도 엔터티가 없으면, 고정된 바이트를 정확히 담고 있는 완전한 캐시 항목을 의존성으로 읽습니다. 따라서 게시된 사본을 가져온 뒤 카탈로그 디렉터리에서 제거된 엔터티도 그 사본으로 여전히 빌드됩니다.
어떤 소스에도 고정된 바이트가 없으면, 빌드는 렌더링이 시작되기 전에 중단됩니다. 이때 E0135가 발생하며, 캐시 항목의 manifest가 lockfile이 고정한 것과 다르면 E0133이 발생합니다. 중단 메시지는 고정 값, 캐시 항목과 그 항목이 담은 다이제스트, 그리고 엔터티의 각 카탈로그 디렉터리 사본과 그 다이제스트를 표시하거나, 어떤 카탈로그 디렉터리에도 엔터티가 없다는 사실을 표시합니다. 해결 방법은 레지스트리에 접근 가능한 상태에서 pull을 실행하는 것입니다. pull은 고정된 버전을 다시 가져오고 가져온 내용이 고정 값과 일치하는지 확인합니다. 레지스트리가 더 이상 해당 바이트를 제공하지 않을 때 pull이 어떻게 동작하는지는 Honoring vs. updating을 참조하십시오.
aggrega pull이 외부 입력을 찾기 위해 실행하는 렌더링과, aggrega serve 또는 aggrega mcp를 통한 빌드나 미리 보기도 같은 방식으로 고정 값을 읽습니다.
빌드 시점의 외부 입력
렌더는 원격 URL의 내용을 요청할 수 있으며(예: 원격 참조가 있는 차트의 values 스키마), 빌드는 렌더가 읽을 수 있는 대상에 추가하기 위해 URL을 가져오는 일이 결코 없습니다. lockfile이 이미 고정한 URL에 대한 요청은 워크스페이스의 입력 저장소에서 제공되며, 어떤 바이트든 렌더에 도달하기 전에 기록된 다이제스트와 대조하여 검증됩니다. 고정되지 않은 URL에 대한 요청은 해당 URL과 그것을 고정하는 단계를 명시하며 중단됩니다. 이 중단을 가져오기로 바꾸는 설정은 없습니다. 빌드가 읽는 입력 집합을 조용히 넓히는 것은 재현 가능한 빌드가 절대 해서는 안 되는 바로 그 일이기 때문입니다.
저장소에 있던 고정된 입력의 사본이 사라진 경우, 그 입력 하나만 lockfile이 이미 기록한 다이제스트로 다시 가져오며, 무엇이든 기록되거나 반환되기 전에 그 다이제스트와 대조하여 확인합니다. 이는 렌더가 보는 내용을 바꿀 수 없으므로(다이제스트는 입력이 고정될 때 이미 확정되었습니다), 클로저에 무언가를 추가하는 것이 아니라 저장소를 복구하는 것이며, lockfile은 바이트 단위로 변경되지 않은 채 유지됩니다. 오프라인 모드에서는 그마저도 할 전송 수단이 없으므로, 사본이 없으면 대신 해당 모드를 명시하며 중단됩니다.
고정은 Release의 의존성이 해석될 때 이루어지므로, 빌드가 읽을 수 있는 대상은 빌드가 시작되기 전에 확정됩니다. aggrega pull이 바로 그 단계이며, 유일한 단계입니다.
플러그인 신뢰 기록
빌드의 여러 동작은 plugins-trust.yaml에 의존합니다. 이 파일은 Release의 잠금 파일 옆에 커밋되는 파일로, 판정을 반환하는 각 연결이 어떤 플러그인으로 확인되었는지를 기록합니다. 여기서 판정을 반환하는 연결이란 ir-verdict 또는 render-verdict 역할의 plugins.governance 연결과 모든 plugins.linter 연결입니다. aggrega pull이 이 파일을 작성하며, 플러그인 신뢰 기록 스키마가 그 필드를 설명합니다. 아래 내용은 빌드 자체가 이 파일로 하는 일만 다룹니다.
빌드는 해당 플러그인 중 어느 것이든 실행되기 전에 기록에 맞춰 검사됩니다. 캐시에서 제공된 플러그인의 아티팩트 다이제스트가 기록된 것과 다르면 그 플러그인은 실행되지 않고 거부됩니다. 이는 그러한 연결이 일반적으로 거치는 확인 방식이며, 기록된 다이제스트가 적용되지 않는 다른 확인 방식은 aggrega pull에서 설명합니다. 또한 .aggrega-config.yaml의 어떤 연결로도 더 이상 설명되지 않는 기록 항목이 있으면 빌드가 중단됩니다. 게이트를 제거해도 렌더링된 바이트는 바뀌지 않으므로, 검토된 게이트 없이 생성된 출력은 그 게이트가 승인한 출력과 정확히 같아 보이기 때문입니다. 중단 시에는 플러그인 이름을 밝히고 의도에 따라 달라지는 두 가지 해결 방법을 제시합니다. 제거가 실수였다면 다시 연결하고, 실수가 아니었다면 명시적으로 제거를 요청하는 것입니다. 또한 바로 실행할 수 있는 명령을 출력합니다. 기록에 아직 없는 연결은 처음 확인된 것이며, 두 비교 모두 이를 이유로 중단하지 않습니다.
빌드는 잠금 파일 항목을 그 항목이 기록한 것에 맞춰 검사하는 것과 똑같이, 해당 플러그인 각각을 그 항목이 기록한 서명에 맞춰 검사합니다. 항목에 검증된 signature가 기록되어 있으면, 빌드는 무엇이든 렌더링하기 전에 그 사실이 가리키는 캐시의 서명 번들을 다시 해시하고, 번들이 없거나 다르면 E0144로 중단합니다. 콘텐츠 캐시에서 읽는 플러그인의 경우, 빌드는 그 번들에서 서명이 어떤 아티팩트에 대해 만들어졌는지도 읽고, 빌드가 읽은 것과 다른 플러그인에 대해 만들어졌다면 서명 요구 사항과 관계없이 E0332로 중단합니다. 다른 항목에서 복사한 signature가 바로 이런 모습입니다. 콘텐츠 캐시가 제공한 플러그인의 경우, 두 거부 모두 aggrega pull --release <release>를 안내합니다. 다음 pull은 플러그인의 서명을 다시 검증하고, 플러그인 자신의 서명을 기록하며, 그 서명이 가리키는 번들을 캐시하고, 다이제스트와 더 이상 일치하지 않는 캐시 사본을 다시 씁니다. 워크스페이스의 신뢰 구성이 빌드가 콘텐츠 캐시에서 읽는 플러그인에 서명을 요구하는 경우(이는 aggrega pull이 서명되지 않은 플러그인을 거부하게 되는 설정과 같으므로, skip_signature_verification와 advisory 레지스트리는 pull을 진행시키듯 빌드도 진행시킵니다), 서명을 기록하지 않은 항목이나 해당 플러그인에 대한 항목이 아예 없으면 빌드가 E0331로 중단되며, 플러그인, plugins-trust.yaml, 서명을 요구하는 설정을 밝힙니다. 해결 방법은 aggrega pull --release <release>이며, 이 명령은 실행할 때마다 레지스트리에서 플러그인의 서명을 검증하고 기록합니다. 카탈로그 디렉터리 중 하나에서 제공되거나 컴파일러 바이너리 내부의 사본에서 제공된 플러그인에는 이 요구 사항이 적용되지 않습니다. 빌드의 다른 부분과 마찬가지로, 이 과정은 이미 머신에 있는 파일을 읽을 뿐이며 어떤 레지스트리에도 요청하지 않습니다.
빌드는 잠금 파일에 담긴 모든 철회와 함께, 이 기록에 담긴 모든 철회를 지명합니다. aggrega pull이 그 플러그인 중 하나에 대해 기록한 마커는 심각도와 관계없이 플러그인, 기록된 심각도, 게시자의 메시지를 지명하는 deprecation: 줄로 보고되며, build.halt_on_deprecated_severity가 고정된 참조에 적용하는 것과 같은 규칙에 따라 그 마커가 빌드도 중단시킬지 결정합니다. Release에 대해 보고하는 다른 모든 표면도 같은 집합을 같은 문구로 지명하며, 그중 어느 것도 이를 이유로 중단하지 않습니다: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, 언어 서버의 검증 및 클로저 응답, 그리고 어시스턴트 도구의 describe와 validate입니다. 존재하지만 읽을 수 없는 기록은 아무것도 기록하지 않은 기록으로 통과되는 대신 빌드를 중단시킵니다.
aggrega build --upgrade는 이 파일을 다시 씁니다. 이 플래그는 --auto-pull을 함축하며 대상 없는 전체 새로 고침을 실행합니다. 이 새로 고침은 모든 의존성을 다시 확인하므로 기록된 모든 식별 정보를 다시 확인하여 다시 쓰고, 어떤 연결로도 설명되지 않는 항목은 모두 제거합니다. 따라서 업그레이드 빌드 후 이 파일이 수정되어 있다면 그 이유는 이것입니다. 이 플래그의 범위는 모든 의존성이며, 기록된 식별 정보는 잠금 파일의 고정 항목은 아니지만 다시 확인되는 대상에 포함됩니다. aggrega pull --upgrade와 달리 빌드 플래그는 대상을 받지 않으므로 하나의 플러그인으로 범위를 좁힐 수 없습니다. 단일 식별 정보를 채택하거나 제거하려면 대신 aggrega pull --upgrade --release <release> <plugin>를 실행합니다. 이 명령은 다른 모든 고정 항목과 다른 모든 기록된 식별 정보를 그대로 둡니다.
범위가 전체이므로 시작하기 전에 확인을 요청합니다. aggrega build --upgrade는 대상 없는 aggrega pull --upgrade와 같은 조건으로 새로 고침을 확인합니다. 두 명령은 같은 동작이므로 같은 질문을 합니다. 비대화형으로 사용할 때는 --yes를 전달하여 미리 응답합니다. 표준 입력이 터미널이 아니고 --yes도 없으면, 빌드는 아무도 할 수 없는 응답을 기다리지 않고 거부합니다. 새로 고침을 하지 않는 빌드는 아무것도 묻지 않습니다.
워크스페이스 확인과 결정성
Release의 스키마상 필수인 manifest: 참조는 Release
파일을 기준으로 확인됩니다. 상대 경로인 catalog_dirs 항목(그리고 상대 경로인 파일 시스템 플러그인 경로)은
그것을 선언한 .aggrega-config.yaml의 디렉터리를 기준으로 확인됩니다. “상대”는
항상 그것을 작성한 파일을 기준으로 한다는 뜻이므로, 경로는 aggrega를 어디에서 호출하든
같은 것을 가리킵니다. 선언한 파일이 없는 --catalog 플래그는
현재 작업 디렉터리를 기준으로 확인됩니다. 레지스트리
참조(oci://…, 허브 참조)는 그대로 둡니다.
워크스페이스 루트는 workspace: 블록을 가진 가장 가까운 상위 .aggrega-config.yaml의 디렉터리이거나, --workspace-root가 지정한 디렉터리입니다. 이렇게 루트가 고정되면 빌드는 호출 위치에 독립적입니다. 프로젝트 루트에서 aggrega build를 실행하든 하위 디렉터리에서 실행하든 바이트 단위로 동일한 IR과 렌더링된 아티팩트가 생성됩니다. 검색되는 카탈로그와 출력에 기록되는 소스 경로가 작업 디렉터리에 따라 바뀌지 않기 때문입니다. (workspace: 표지도 --workspace-root도 없으면 작업 디렉터리가 루트가 되므로 출력은 그곳을 기준으로 합니다. 다만 작업 디렉터리가 아무것도 기준으로 삼지 않고 --release가 Release를 절대 경로로 지정하는 경우에는, 루트를 Release 자신의 폴더에서 다시 찾으므로 검색되는 카탈로그와 출력에 기록되는 경로는 명령을 어디에서 실행하든 그 Release가 속한 프로젝트의 것이 됩니다. configuration.md를 참고하십시오.) 그렇게 해도 워크스페이스를 찾지 못하고 아무것도 워크스페이스를 지정하지 않으면, 빌드는 루트로 사용한 폴더가 워크스페이스 안에 있지 않다고 표준 오류에 경고하고 그 폴더를 워크스페이스로 만드는 명령을 알려 줍니다. 먼저 의존성을 확인하도록 요청된 빌드는 무엇이든 가져오기 전에 거부됩니다. 그 확인 과정이 채우는 캐시가 그 폴더에 기록되어 그 폴더를 워크스페이스로 만들기 때문입니다. 먼저 아무것도 확인하지 않는 빌드는 여전히 렌더링하지만, 같은 이유로 lockfile이 고정하고 캐시에 더 이상 없는 외부 입력은 다시 가져오지 않습니다. 그 입력을 요청하는 플러그인은 오프라인 상태일 때의 문장을 전달받는 것처럼 그 대신 거부 문장을 전달받으며, 빌드는 그 플러그인이 이를 어떻게 처리하는지 보고합니다. 존재하지 않는 폴더를 지정하는 --workspace-root 또는 AGGREGA_WORKSPACE_ROOT는 빌드가 다른 어떤 작업을 하기 전에 거부되며, 둘 중 그 값을 제공한 쪽을 명시합니다.
환경 변수
build가 읽는 워크스페이스 설정은 환경을 통해 재정의할 수 있으며, 커밋된 구성보다 우선하고 모든 플래그보다는 후순위입니다: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS(OS 경로 목록 구분자로 구분하며 절대 경로를 지정합니다), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY, AGGREGA_WORKSPACE_ROOT. 전체 목록과 우선순위 모델은 environment-variables.md를 참조하십시오.
출력
렌더링된 아티팩트는 명령을 어느 폴더에서 실행하든(루트 자체, 그 아래의 폴더, 또는 --workspace-root나 AGGREGA_WORKSPACE_ROOT로 루트를 지정한 다른 위치의 폴더) 워크스페이스 루트 아래의 dist/에 놓이며, 마지막 줄에 그 디렉터리가 전체 경로로 표시됩니다:
Build completed: 4 files written to <workspace>/dist여기서 <workspace>는 워크스페이스 루트를 나타내며, 해당 줄에는 전체 경로로 표시됩니다. 워크스페이스를 찾지 못하고 아무것도 워크스페이스를 지정하지 않으면 명령을 실행한 폴더가 루트가 되므로 dist/는 그곳에 기록됩니다. 워크스페이스 밖을 가리키는 링크인 dist는 그 안의 어떤 것도 제거하거나 기록하기 전에 거부됩니다. 경계를 선언하지 않은 Release는 프로바이더별로 기록합니다: dist/<provider>/<files>. directory:가 없는 선언된 경계는 경계별, 프로바이더별로 기록합니다: dist/boundaries/<boundary-path>/<provider>/<files>. Release 경계에 운영자가 작성한 directory: 및 subDirectory: 재정의는 대상 경로를 변경합니다. (path, provider)별 병합은 동일한 평가 경로로 해석되는 기여자들을 합칩니다.
빌드가 쓰지 않은 파일
빌드는 자신의 파일을 쓰고 자신이 쓰지 않은 것은 아무것도 제거하지 않습니다. 단, 한 가지 예외가 있습니다. dist/boundaries/는 빌드가 전체를 다시 생성하므로 쓰기 전에 비워지며, 따라서 다른 변형의 빌드가 그곳에 남긴 파일이 더 이상 그 파일을 생성하지 않는 트리에 남아 있지 않습니다. dist/의 나머지는 모두 그대로 둡니다. 이전 빌드가 썼지만 이번 빌드는 더 이상 생성하지 않는 파일, 경계의 directory:가 이전 실행에서 그곳에 둔 파일, 직접 그곳에 둔 파일 모두 마찬가지입니다. 빌드는 남은 파일과 의도적으로 그곳에 보관하는 파일을 구별할 수 없기 때문입니다.
대신 빌드는 이를 알려 줍니다. 파일을 모두 쓰고 나면 빌드는 dist/ 자체와, 그 아래에서 파일을 썼거나 더 깊은 곳에 파일을 쓰기 위해 거쳐 간 모든 디렉터리를 살펴보고, 그곳에서 이번 실행에서 쓰지 않은 각 파일을 표준 오류에 출력하는 하나의 경고로 지목합니다. 파일은 dist/를 기준으로 한 상대 경로로 정렬되어 지목되므로, 같은 트리는 실행할 때마다 같은 방식으로 보고됩니다:
warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"그런 다음 마지막 줄이 그 개수를 셉니다:
Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write빌드가 아무것도 쓰지 않았고 그 아래에도 아무것도 쓰지 않은 디렉터리는 살펴보지 않으므로, dist/ 아래에 보관하는 자신의 폴더가 파일 단위로 나열되지는 않습니다. 그러한 파일을 찾지 못한 빌드는 경고를 출력하지 않으며, 마지막 줄은 출력에 표시된 것과 같습니다. 어느 경우든 빌드가 쓰는 파일은 같은 바이트입니다. 두 빌드를 비교하거나 아무것도 없는 상태에서 시작하려면 빌드하기 전에 dist/를 제거하십시오.
aggrega serve의 aggrega/build 요청과 어시스턴트의 build 도구(aggrega mcp)는 같은 단계를 거쳐 쓰므로 같은 파일을 같은 문장으로 지목합니다. 데몬은 응답의 notices 중 하나로, 도구는 advisories의 마지막 항목으로 지목합니다. 드라이 런은 아무것도 쓰지 않으므로 이 중 어느 것도 보고하지 않습니다.
YAML 들여쓰기
렌더링되는 모든 YAML 아티팩트(docker-compose 파일, Helm 차트 템플릿과 values, Kubernetes 매니페스트)는 균일한 들여쓰기 너비로 출력됩니다. 너비는 .aggrega-config.yaml의 build.yaml_indent로 설정하며 기본값은 2(해당 형식의 관례적인 너비)입니다:
build: yaml_indent: 2 # default; accepts 2 through 9너비는 모든 렌더러가 공유하는 단일 마셜링 지점에서 적용되므로, 동일한 입력을 여러 번 실행해도 출력은 바이트 단위로 동일하게 유지됩니다. [2, 9] 범위를 벗어난 값은 구성 스키마 검증에서 거부됩니다.
컴파일된 그래프 돌려받기
--ir-graph는 이 빌드가 해석한 그래프를 JSON으로 표준 출력에 기록합니다. 이는 추가적인 동작입니다: 아티팩트는 여전히 dist/에 기록되고, 요약도 여전히 출력되며, 렌더링된 바이트는 변하지 않습니다. 그래프는 빌드가 표준 출력에 출력하는 다른 모든 내용보다 먼저(하나의 JSON 문서와 하나의 후행 줄바꿈으로) 출력되므로, 스트림을 디코딩하는 소비자는 그것을 읽고 멈추면 됩니다.
돌려받는 그래프는 렌더링이 사용한 바로 그 그래프이므로, 같은 Release를 다시 해석한 결과가 아니라 옆에 있는 아티팩트를 생성한 빌드를 정확히 기술합니다. --dry-run과 함께 사용할 수 있습니다: 그래프가 기록되고 그 뒤에 아티팩트 보고가 이어지며, 디스크에는 아무것도 기록되지 않습니다.
작성자가 민감하다고 선언한 값은 aggrega inspect에 설명된 구조화된 형식으로 그래프에서 제외되며, 소비하는 컴포넌트의 소켓이 리프를 민감하다고 선언한 경우에는 연결의 values와 infra도 여기에 포함됩니다. --ir-graph와 함께 --unredacted를 지정하면 aggrega inspect --unredacted가 명시하는 조건에 따라 그 값을 대신 출력합니다: 이 플래그는 그래프에만 적용되고 다른 것에는 적용되지 않으며(트레이스 파일에는 별도의 --trace-unredacted가 있고, 렌더링된 아티팩트에서는 값이 제외되지 않습니다), 그 경우 출력이 전달되는 모든 곳에 해당 값이 평문으로 담깁니다. --ir-graph 없이 지정하면 드러낼 대상이 없으므로 거부됩니다.
같은 의미의 같은 플래그가 aggrega inspect와 aggrega validate에도 있습니다.
빌드를 기록하지 않고 미리 보기
--dry-run은 빌드가 실행하는 것과 동일한 컴파일을 실행합니다. 동일한 의존성 게이트, 동일한 렌더링, 동일한 provider를 사용하며, 출력할 내용을 기록하는 대신 출력합니다. 각 아티팩트는 차지할 경로와 담을 내용과 함께 보고됩니다:
aggrega build --release releases/production.yaml --dry-run==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==apiVersion: v1kind: ConfigMap...
Total build time: 2.5sDry run: 1 file would be written to <workspace>/dist; nothing was written아티팩트는 빌드가 기록하는 순서대로 보고되므로 동일한 입력은 동일한 바이트를 동일한 순서로 보고하며, 보고되는 경로는 빌드가 기록할 경로입니다. 이 경로는 워크스페이스 루트 아래에 있으며, 위에서 <workspace>로 표시된 부분이 전체 경로로 표시됩니다.
기록되지 않는 것. 출력 디렉터리는 현재 상태 그대로 유지됩니다. 정리되지도 않으므로 이전 빌드의 출력은 dry run 후에도 그대로 남습니다. lockfile은 기록되지 않습니다. .trace/에는 아무것도 기록되지 않습니다.
외부 입력은 일반 빌드에서와 똑같이 동작합니다. 이는 빌드 시점의 외부 입력에서 설명하는 조건을 따릅니다. 따라서 dry run은 그것이 대신하는 빌드가 읽을 것과 동일한 고정된 클로저를 읽으며, 보여 주는 내용은 해당 빌드가 기록할 내용입니다.
참조가 거부된 경우, 실행은 도달하지 못한 참조를 모두 나열하고 이를 고정하는 명령을 안내합니다:
note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit: - https://charts.example.com/values-schema.json Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run againaggrega pull을 한 번 실행하면 dry run에 필요한 모든 것이 갖춰지며, 그 외에는 달라지는 것이 없습니다.
dry run에는 lockfile이 필요하며, lockfile을 채우지 않습니다. 빌드는 기본적으로 읽기 전용이며, dry run은 채우기가 어떤 방식으로 요청되든 이를 유지합니다. --auto-pull과 --upgrade는 즉시 거부되며(아래 참조), auto_pull 워크스페이스 설정은 해당 호출에 한해 재정의되므로 기본적으로 채우기를 수행하는 워크스페이스도 미리 볼 수 있습니다. lockfile이 없으면 dry run은 일반 읽기 전용 빌드와 동일한 해결 방법을 안내하며 중단됩니다: 먼저 aggrega pull을 실행하십시오.
거부하는 플래그. 세 가지 플래그는 기록을 수행하므로 dry run과 함께 사용하면 정직한 결과가 나올 수 없습니다. 기록을 무시하면 요청된 채우기가 사라지고, 기록을 수행하면 dry run이 하는 유일한 약속을 깨게 됩니다. 각 조합은 작업을 시작하기 전에 중단되며, 전달한 플래그와 대신 실행할 단계를 안내합니다:
| 함께 사용한 플래그 | 거부하는 이유 |
|---|---|
--auto-pull | lockfile을 채웁니다. aggrega pull을 별도 단계로 실행하십시오 |
--upgrade | 모든 의존성을 다시 해석하고 lockfile을 다시 씁니다. aggrega pull --upgrade를 별도 단계로 실행하십시오 |
--trace | 노드별 파일을 .trace/에 기록합니다. 트레이스 빌드는 --dry-run 없이 실행하십시오 |
그 밖의 모든 것은 정상적으로 조합됩니다. --verify-determinism은 각 노드를 두 번 렌더링하고 어느 것도 기록하지 않은 채 바이트를 비교하며, --catalog, --quiet, --progress, --debug 및 경고 필터는 기록하는 빌드에서와 똑같이 동작합니다.
용도와 용도가 아닌 것. dry run은 “이 Release가 무엇을 출력하는가”에 답하며, 이는 렌더링만이 답할 수 있는 질문입니다. 따라서 렌더링 없이 정확성을 검사하는 aggrega validate나 렌더링 전에 그래프를 조회하는 aggrega inspect를 대신하지 않습니다. 원하는 답이 아티팩트 자체일 때 dry run을 사용하십시오. 예를 들어 Release 변경이 출력에 미치는 영향을 검토하거나, dist/에 무엇이든 커밋하기 전에 Recipe 편집을 확인할 때입니다.
트레이스 출력
--trace 플래그는 컴파일러의 모든 중간 상태를 담는 노드별 디버그 덤프를 켭니다. 출력은 워크스페이스 루트 아래 .trace/에, dist/ 옆에 위치합니다(그 아래에는 절대 두지 않습니다. 형제 배치는 .git/, .terraform/, node_modules/의 관례를 따르며 dist/를 순수하게 배포 가능한 상태로 유지합니다).
디렉터리 구조는 경계별, 인스턴스별입니다.
.trace/└── boundaries/ └── <boundary-path>/ └── <instance-id>/ ├── 01-pillars-initial.yaml ├── 02-provides-evaluation.yaml ├── 03-inject-hydration.yaml ├── 04-inject-mapping.yaml ├── 05-source-resolution.yaml ├── 06-source-locals.yaml ├── 07-values-mapping.yaml ├── 08-workload-synthesis.yaml ├── 09-artifact-evaluation/ │ └── <per-artifact-file>.yaml ├── 09b-feature-rendering-boundary.yaml ├── 10-engine-synthesis/ │ └── <per-synthesized-file>.yaml ├── 11-engine-emission.log └── 12-labels-injected.log각 슬롯은 특정 컴파일러 상태를 담습니다.
01-pillars-initial.yaml— 템플릿이 읽는 컨텍스트의 노드별 스냅숏으로, 해석 이후, 단계별 변경이 일어나기 전에 기록됩니다..values,.infra,.context,.parameters,.metadata를 담습니다.02-provides-evaluation.yaml— provides 평가 이후 해석된provides:출력입니다.03-inject-hydration.yaml— inject 하이드레이션 이후 병합된.context.inject파이프입니다(업스트림provides를 소비자 쪽에서 본 모습).04-inject-mapping.yaml— FeatureRecipeinjectMapping재작성 이후의.context.inject파이프입니다.05-source-resolution.yaml— provider가 소비할, 파싱된source:내용입니다. Recipe가source:를 선언한 경우에만 존재합니다.06-source-locals.yaml— 해석된locals:블록입니다. 소스 해석은source:템플릿을 평가하기 전에.locals를 게시하므로, 이 슬롯은 Recipe가source:를 선언하는지와 관계없이 기록됩니다.07-values-mapping.yaml— 렌더링된valuesMapping:출력입니다(provider가 받는 딕셔너리). Recipe가valuesMapping:을 선언한 경우에만 존재합니다.08-workload-synthesis.yaml—workload:템플릿이 평가되고 그 출력이 파싱될 당시의 컨텍스트입니다. Recipe가workload:를 선언한 경우(인라인 또는$import:로 로드)에만 존재합니다. 파싱된Workload자체는 이 슬롯에 없습니다. 진행 중이 아니라 확정된 뒤인09-artifact-evaluation/부터 나타납니다.09-artifact-evaluation/— 평가된 아티팩트마다 파일 하나입니다. Recipe가artifacts:를 선언한 경우(항목을 인라인으로 또는 항목별$import:로 로드)에만 존재합니다.09b-feature-rendering-boundary.yaml— 노드의 렌더링이 끝날 때, 즉 노드에 첨부된 FeatureRecipes가 리소스를 생성한 후의 컨텍스트이며, 그 옆에 파싱된workload가 놓입니다. 모든 노드에 대해 기록됩니다.10-engine-synthesis/— provider가 Workload로부터 생성한 합성 매니페스트마다 파일 하나입니다(helm/compose workload 모드). provider가 합성 경로를 실행한 경우에만 존재합니다.11-engine-emission.log— 노드에 대한 출력 후 요약(파일 수, 출력 경로)입니다.12-labels-injected.log— 노드의 렌더링된 출력에 기록된 출처 레이블과 어노테이션입니다.
03-inject-hydration.yaml부터는 노드의 컨텍스트를 보여 주는 슬롯이, 그 슬롯이 포착한 파이프가 어떤 메커니즘으로든 키를 하나 이상 전달할 때마다 .context.inject 블록을 지닙니다. 메커니즘은 env, file, arg, 또는 inject 매핑, FeatureRecipe의 injectMapping, 혹은 컴포넌트 자체의 inject: 블록이 기록하는 다른 이름의 메커니즘입니다. 이러한 사용자 지정 메커니즘으로만 전달하는 노드도 이 블록을 보여 주며, 그 메커니즘은 자체 이름 아래에, 그 키는 all에 나타나고, 민감하다고 선언된 값은 두 곳 모두에서 <redacted>로 표시됩니다. 파이프가 아무것도 전달하지 않는 동안 취한 슬롯에는 .context.inject 블록이 없습니다.
트레이스 작성기는 논블로킹입니다. 트레이스는 컴파일 경로 안이 아니라 컴파일과 나란히 디스크에 기록됩니다. 컴파일 지연 시간은 트레이스 I/O의 영향을 받지 않습니다. --trace가 켜져 있든 꺼져 있든 같은 컴파일은 같은 실제 시간 안에 끝납니다.
트레이스의 민감 선언 값
작성자가 민감하다고 선언한 데이터, 즉 sensitive: true를 지닌 스키마 리프나 그런 provides 키에서 내용을 받은 전달 키는 트레이스에 고정 텍스트 <redacted>로 기록됩니다. 키는 유지되고 값만 대체되므로, 슬롯에는 노드가 어떤 리프와 어떤 전달 키를 지니는지가 여전히 표시됩니다. 같은 블록에서 선언되지 않은 형제 항목은 값을 그대로 출력합니다. 대체는 선언만을 따릅니다.
FeatureRecipe가 자체 injectMapping을 통해 전달하는 값도 숨겨집니다. 이는 빈 inject 목록을 선언한 슬롯이 전달을 넘기는 경로이며, inject 전용 자격 증명 실현이 거치는 경로입니다. 이러한 매핑이 기록하는 전달 키는 그 자체가 템플릿이므로 어떤 선언도 그 키를 지정하지 않으며, 대신 매핑 자체의 텍스트를 읽습니다. 그 텍스트가 연결된 Feature가 sensitive: true로 선언한 values 또는 infra 리프를 참조하면, 매핑이 생성한 모든 전달 키가 <redacted>로 표시됩니다. 판단이 키 단위가 아니라 연결 단위이므로, 민감한 내용을 전혀 지니지 않은 키도 마찬가지입니다. 선언된 것을 아무것도 참조하지 않는 매핑은 키를 그대로 출력합니다.
민감 선언 데이터로부터 템플릿이 계산한 값도, 그 자체의 키에 선언이 없더라도 숨겨집니다. 이를 식별하는 것은 작성자가 쓴 참조입니다. 템플릿이 민감 선언 리프를 읽는 locals: 항목은 숨겨지며, 그런 source: 필드도 마찬가지입니다. 판단은 보수적입니다. 객체 전체에 접근하는 템플릿은 그 아래의 모든 선언된 리프에 접근하는 것이므로, {{ range $k, $v := .values.creds }}는 creds 아래에 선언된 것이 하나라도 있으면 출력이 숨겨집니다. 또한 이미 숨겨진 형제 항목을 읽는 locals: 항목도 차례로 숨겨집니다. 같은 형태이지만 선언된 것을 아무것도 읽지 않는 형제 항목은 그대로 출력됩니다.
uses 에지를 따라 전달되는 값은 소비하는 노드가 아니라 대상의 선언을 기준으로 숨겨지며, 에지가 값을 전달하는 두 표면 모두에서 숨겨집니다. .context.uses.<alias>.provides는 대상 component가 게시한 것을 재현하므로, 그 값을 결정하는 것은 대상의 스키마입니다. 대상이 민감하다고 선언한 provides 키는 소비자가 아무것도 선언하지 않았더라도 소비자의 슬롯에서 <redacted>로 표시됩니다. 에지 자체의 inject 블록이 그 키를 소비하는 component의 전달 키로 라우팅하면, .context.inject도 그 전달 키를 숨깁니다. 이는 연결의 inject 매핑이 이미 따르는 것과 같은 규칙이며, 같은 선언을 읽습니다. 숨김은 에지 단위이므로 같은 provides 키 이름을 게시하는 두 에지는 독립적으로 결정됩니다. 대상이 이를 선언한 에지는 숨겨지고, 다른 에지는 그대로 출력됩니다. 에지의 나머지 부분, 즉 대상, 소켓, 레이블, 그리고 inject 매핑 자체의 키 이름은 대상의 provides 선언이 결정하는 대상이 아니므로 그대로 출력됩니다.
에지 자체에 작성된 연결별 values와 infra는 대신 소비하는 컴포넌트의 소켓이 결정합니다. 즉 그 소켓이 선언하는 valueSchema와 infraSchema이며, 이는 해당 구성을 검증하는 기준이 되는 계약입니다. 어느 한 계약이 sensitive: true로 선언한 리프는 .context.uses.<alias>.values 또는 .context.uses.<alias>.infra에서 키는 유지된 채 <redacted>로 표시되며, 계약이 선언한 기본값을 취하고 있는 리프도 마찬가지입니다. 선언되지 않은 형제 항목은 그대로 출력됩니다. 여기서는 대상의 선언이 아무 역할도 하지 않으며, 숨김은 연결 단위이므로 소켓이 읽을 수 있다고 선언한 연결에 있는 같은 이름의 리프는 그대로 출력됩니다.
연결에 작성된 attachment는 해당 연결의 에지 아래 .context.uses.<alias>.features.<slot>에 표시되며, 각각은 자신의 Feature의 선언, 즉 component가 그 Feature를 직접 보유할 때 그 Feature를 결정하는 것과 같은 선언을 기준으로 숨겨집니다. Feature가 sensitive: true로 선언한 values 또는 infra 리프는 <redacted>로 표시되며, Feature가 민감하다고 선언한 attachment의 해석된 provides 키도 마찬가지입니다. 각 키는 유지됩니다. attachment의 유형, 버전, 레이블, 그리고 Feature가 선언하지 않은 모든 리프와 provides 키는 그대로 출력되므로, 게시된 로케이터는 그것이 가리키는 자료 옆에서 읽을 수 있는 상태로 남습니다. 숨김은 연결 및 슬롯 단위이므로, 두 연결에 작성된 같은 Feature는 각 연결에서 따로 결정됩니다. 컴포넌트나 소켓에서 sensitive: true를 선언한 슬롯은 attachment가 비밀 자료를 다룬다는 것을 나타낼 뿐, 그 자체로 어떤 리프도 숨기지 않습니다. 어떤 리프를 숨길지는 Feature가 선언할 몫입니다. component 자체의 attachment는 트레이스에 .features 블록이 없으므로 슬롯이 보여 주는 블록에 포함되지 않습니다. workload: 템플릿이 그로부터 읽는 내용은 아래의 재렌더링에서 다룹니다.
파싱된 Workload는 빌드가 출력한 문서를 캡처한 것이 아니라 재렌더링한 것이며, 이를 담는 슬롯인 09-artifact-evaluation/, 10-engine-synthesis/, 09b-feature-rendering-boundary.yaml은 그 옆의 workload_note 항목에서 이를 밝힙니다. 렌더링된 문서는 어떤 문자가 어떤 선언에서 왔는지 아무것도 기록하지 않으므로, 그 안에서 대체할 키가 없습니다. 대신 트레이스가 보여 주는 것은 민감 선언 데이터가 이미 <redacted>로 표시되는 컨텍스트를 대상으로 같은 workload: 템플릿을 한 번 더 평가한 결과입니다. 템플릿은 문자열이 있던 자리에서 문자열을 보므로, 결과는 출력된 문서의 형태를 유지합니다. 같은 필드가 같은 위치에 있고, 숨겨진 데이터 자체의 위치에 <redacted>가 들어가며 그 주변의 리터럴 텍스트는 바뀌지 않습니다.
재렌더링이 출력된 것과 다른 두 가지 경우이며, 노트에 둘 다 명시됩니다.
- 값의 내용에 따라 분기하는 템플릿은 다르게 렌더링됩니다. 특정 값에 대한
eq, 길이 검사, 해시나 인코딩은 각각<redacted>를 보고 다른 결과, 즉 다른 분기, 다른 길이, 다른 다이제스트를 생성합니다. 이 때문에 트레이스는 출력된 문서를 보여 준다고 결코 주장하지 않습니다. - 어떤 선언도 지정하지 않은 데이터는 변경 없이 전달됩니다. 대체는 축이 지정하는 것을 다룹니다. 즉 선언된
values/infra리프, 표시된 전달 키, component 자신의 Component가 민감하다고 선언한provides키, 소비된 대상의 선언된provides, 연결 자체의values또는infra중 그 소켓이 민감하다고 선언한 리프, component가 직접 보유한 attachment(.features.<name>에서 읽음) 또는 연결에 작성된 attachment의 선언된 리프나provides키, 그리고 이들로부터 계산된locals:또는source:값입니다. 이는 템플릿이 발생시킨 거부가 숨겨지는 기준과 같은 데이터입니다. 다른 경로로 템플릿에 도달하는 데이터, 예를 들어 Recipe가 선언된 리프로부터 값을 계산했지만 어떤 선언도 지정하지 않은provides키는 재렌더링에서 출력된 문서와 정확히 같게 나타납니다.
재렌더링을 전혀 생성할 수 없으면, 슬롯은 workload: 키를 유지하고 문서를 그 사실을 알리며 --trace-unredacted를 언급하는 한 줄로 대체합니다. 이 표시는 의도된 것입니다. 투영이 그냥 사라지면 workload:를 전혀 선언하지 않은 Recipe와 구별할 수 없기 때문입니다.
.trace/를 안전하다고 여기기 전에 알아 둘 한계가 하나 있습니다. dist/는 가려지지 않습니다. 렌더링된 아티팩트는 배포 대상이므로 렌더링이 생성한 그대로 출력되며, 트레이스의 재렌더링은 이에 전혀 영향을 주지 않습니다. 같은 입력은 --trace가 켜져 있든 꺼져 있든 바이트 단위로 동일하게 렌더링됩니다.
.trace/도 민감한 자료를 담고 있다고 보고 dist/를 다루는 방식대로 다루십시오.
보류된 값 표시하기
--trace-unredacted를 --trace와 함께 지정하면 선언된 민감 값을 대체 텍스트 대신 실제 값으로 트레이스 파일에 기록합니다. 이 플래그가 존재하는 이유는 디버깅 대상이 바로 보류된 값인 경우가 있기 때문입니다. 잘못된 attachment에서 도착한 자격 증명은 둘 다 보류된 것으로 표시되면 올바른 자격 증명과 똑같아 보입니다.
이 플래그는 빌드가 실제로 출력한 문서를 캡처하는 방법이기도 합니다. 보류되는 것이 없으면 대체할 것도 없으므로 workload: 슬롯은 재렌더링이 아닌 출력된 문서 자체를 담으며, workload_note 항목은 나타나지 않습니다.
이 플래그에는 세 가지 제약이 있습니다.
- 기록하는 모든 파일이 스스로 무엇인지 밝힙니다. 실행 중 생성되는 각 트레이스 파일은 플래그 이름과 함께 선언된 민감 값이 아래에 평문으로 나타난다는 주석으로 시작하므로, 나중에 버그 보고서에 첨부되거나 공유 디렉터리에 남겨진 파일도 자체 경고를 지니게 됩니다. 이 주석은 파일 자체 형식에서 유효하므로 파일은 여전히 파싱됩니다.
.trace/에만 영향을 미치고 그 밖에는 아무것도 바꾸지 않습니다. 렌더링된 아티팩트는 이 플래그의 유무와 관계없이 바이트 단위로 동일합니다. 이 플래그는 디버그 파일이 보여 주는 내용을 바꿀 뿐 빌드가 생성하는 결과는 절대 바꾸지 않으며,aggrega inspect레이아웃과 실패한 빌드가 출력하는 진단 텍스트도 두 상태에서 동일합니다.- 호출 시에만 적용됩니다. 이 플래그에 대한 구성 설정은 없으므로, 한 번 켜 두어 이후 워크스페이스를 빌드하는 모든 사람에게 켜진 상태로 남게 할 수 없습니다.
--trace없이 이 플래그를 요청하면, 이행할 수 없는 요청을 받아들이는 대신 두 플래그를 모두 명시한 메시지와 함께 빌드가 중단됩니다.
트레이스와는 별도로, 빌드는 선언된 민감 자료를 리터럴 값으로 담는 delivery key마다 하나의 권고 메시지를 출력하며, 여기에는 component, target, attachment, delivery key가 명시됩니다. 이 메시지는 빌드를 중단시키지 않으며 --no-unsupported-field-warnings로도 억제되지 않습니다. 해당 플래그는 작성한 내용 중 target이 이행할 수 없는 부분을 다루며, 이는 다른 부류입니다.
키워드, 키워드를 작성하는 두 위치, 권고 메시지의 정확한 문구, 그리고 선언으로 달성할 수 있는 범위의 전체 한계는 vocabulary/compact-form-authoring.md의 “Declaring a leaf sensitive”에 있습니다.
--trace를 사용해야 하는 경우
- 렌더링된 manifest에 예상한 값이 들어 있지 않은 이유를 진단할 때: 패스별 덤프를 따라가며 값이 처음으로 빠진 슬롯을 찾습니다.
- 컴파일러 업그레이드 후 결정성을 검증할 때: 같은 입력을
--trace로 두 번 컴파일하면 바이트 단위로 동일한 트레이스 덤프가 생성되며, 슬롯별 차이가 있으면 그것으로 회귀 위치를 특정할 수 있습니다. - 카탈로그 작성을 반복할 때:
04-inject-mapping.yaml스냅숏과06-source-locals.yaml스냅숏을 비교하면 Recipe의 템플릿이 평가 시점에 무엇을 보는지 알 수 있습니다.
예시
로컬 카탈로그를 기준으로 Release를 컴파일합니다:
aggrega build --release releases/production.yaml별도의 카탈로그 디렉터리를 지정해 컴파일합니다:
aggrega build --release releases/production.yaml --catalog ../platform-catalog/아무것도 쓰지 않고 Release가 출력할 내용을 확인합니다:
aggrega build --release releases/production.yaml --dry-run디버깅을 위해 트레이스 덤프와 함께 컴파일합니다:
aggrega build --release releases/production.yaml --trace컴파일 후 .trace/boundaries/<boundary>/<instance>/에서 패스별 상태를 확인합니다. .trace/ 디렉터리는 --trace 실행 때마다 덮어쓰이며, 이전 트레이스 상태는 컴파일 간에 보존되지 않습니다.
상호 참조
aggrega-pull— OCI 레지스트리에서 카탈로그 엔터티를 가져와 로컬 카탈로그에 넣습니다.aggrega-validate— 아티팩트를 내보내지 않고 카탈로그, Release 클로저 또는 단일 엔터티의 정확성을 검사합니다. 빌드가 실행하는 의존성 검증을 렌더링 없이 수행합니다.aggrega-lint— 동일한 세 가지 범위에서 카탈로그 게시 관례를 검사합니다.aggrega-inspect— 그래프 확정 후 렌더링으로 진행하지 않고 IR 그래프를 조회합니다.- 오류 — CLI에 표시되는 분류된 오류 렌더링 형식입니다.
개요
aggrega build [flags]설명
Compile an Aggregate and Release pair into provider-native artifacts under eachboundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,declares the boundaries, and routes each component to a provider. What aprovider emits is the provider's own shape — Helm manifests, a redistributableHelm chart, docker-compose YAML — so the output directory holds whatever theproviders this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder thecommand is run from, and the closing line names it in full. A run that finds noworkspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first tocreate one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makesthe rendered tree reviewable as a diff.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--auto-pull | false | 빌드 전에 pull 단계를 실행합니다. Release의 의존성을 프로세스 내에서 lockfile과 캐시로 해석한 다음, 이를 기반으로 빌드합니다. 이는 워크스페이스 auto_pull 설정이 수행하는 것과 동일한 프로세스 내 채우기이며, 워크스페이스 구성을 편집하지 않고 단일 빌드에 대해 켜는 것입니다. 단독으로 사용하면 증분 채우기입니다. 기존 고정은 유지되고, 고정이 없는 참조는 해석되어 추가됩니다 |
--catalog | [] | 카탈로그 디렉터리이며 반복할 수 있습니다. 각 —catalog <dir>는 카탈로그 검색 스택의 앞에 추가됩니다(처음 일치하는 항목이 우선). 스택은 워크스페이스 catalog_dirs이거나, 워크스페이스 구성이 workspace.releases 아래에서 자체 디렉터리를 지정한 Release의 경우 해당 Release의 디렉터리이며, 워크스페이스 루트에 catalog라는 이름의 디렉터리가 있으면 그것으로 끝납니다. 비어 있게 작성된 catalog_dirs 목록은 로컬 카탈로그를 전혀 읽지 않습니다. |
--debug | false | 사람이 읽을 수 있는 상세 진단을 stderr에 출력합니다. 단계별 실제 소요 시간과 엔터티/의존성 개수가 포함됩니다. —quiet보다 우선합니다. 상세 출력은 항상 출력됩니다. 기계가 읽을 수 있는 노드별 중간 파일을 .trace/에 쓰는 —trace와는 다릅니다 |
--detail | false | 빌드는 기본적으로 읽기 전용이며 해석 세부 정보를 출력하지 않습니다. —auto-pull이 전달되었거나 워크스페이스가 auto_pull을 활성화하여 pull 단계가 실행되면, 빌드는 lockfile이 이미 있는지와 관계없이 프로세스 내에서 lockfile을 채우며, 이 플래그는 해석된 엔터티마다 그 채우기가 무엇을 했는지 출력합니다. 레지스트리에서 새로 가져옴, 캐시 슬롯 재사용, 로컬 카탈로그에서 찾음, 컴파일러 바이너리 내부에서 제공, 또는 외부(Release가 지정한 파일이나 항목에서 읽은 Release 자체의 Aggregate 또는 Manifest) 중 하나입니다. pull 단계가 실행되지 않으면 엔터티별 행 대신 그렇다는 한 줄을 출력합니다. stdout 전용이며 저장되지 않습니다 |
--disable-plugin-cache | false | 이 빌드에서 디스크의 영구 플러그인 컴파일 캐시를 건너뛰고, 빌드가 끝나면 폐기되는 메모리 내 캐시에서 플러그인 게스트를 새로 컴파일합니다. 기본값은 꺼짐이며, 이 경우 빌드 간에 공유 디스크 캐시를 재사용합니다. 렌더링 출력은 바뀌지 않습니다 |
--dry-run | false | Release를 렌더링하고, 쓰는 대신 무엇을 내보낼지 출력합니다. 각 아티팩트의 예정 경로와 내용이 stdout으로 출력되며, 출력 디렉터리와 lockfile은 변경되지 않습니다. 외부 입력은 일반 빌드와 정확히 동일하게 동작합니다. 고정된 입력은 콘텐츠 주소 지정 저장소에서 제공되고(blob이 없으면 다이제스트로 다시 채워짐), 고정되지 않은 외부 URL을 요청하는 렌더링은 해당 URL을 명시하며 중단됩니다. 따라서 dry run이 보여 주는 것이 곧 빌드가 쓸 내용입니다. 각각 쓰기를 수행하는 —auto-pull, —upgrade, —trace와는 함께 사용할 수 없습니다. 의존성 채우기나 추적 빌드는 별도 단계로 실행하십시오. —policy-input과는 함께 사용할 수 있으며, 그 경우 그 플래그의 파일이 이 명령이 쓰는 유일한 것입니다 |
--ir-graph | false | 이 명령이 이미 생성하는 모든 것에 더해, 이번 실행에서 계산한 IR 그래프를 JSON으로 stdout에도 씁니다. 작성자가 민감하다고 선언한 값은 여기에서 제외됩니다. 대신 출력하려면 —unredacted를 전달하십시오. 아티팩트는 여전히 쓰이고 요약도 여전히 출력되며, 그래프는 둘보다 먼저 쓰입니다 |
--no-unsupported-field-warnings | false | 지원되지 않는 필드 경고 부류를 표시하지 않습니다. 이는 작성한 내용 중 대상이 이행할 수 없는 것에 대해 대상이 발생시키는 알림으로, 대상이 표현할 수 없는 Workload 필드(compose 같은 낮은 충실도 대상의 경우)나 노드의 입력 종류에 대해 대상이 처리하지 않는 aggrega.ai/ 어노테이션이 해당합니다. 다른 렌더링 경고는 계속 표시됩니다. 표시 전용이며 렌더링 출력은 바뀌지 않습니다 |
--policy-input | — | 각 거버넌스 역할이 그곳에 첨부된 플러그인에 건네는 페이로드를 JSON 한 줄로 이 디렉터리에 씁니다. 내용은 빌드가 플러그인에 건네는 것과 정확히 같으며, 빌드가 플러그인에게 감추는 값은 모두 감춰집니다. annotation-transform, label-transform, ir-verdict의 경우 이 파일은 해당 역할의 정책이 읽는 input 문서입니다. render-verdict의 경우 정책이 읽기 전에 정책 엔진이 페이로드의 형태를 바꾸므로(각 아티팩트의 documents가 그로부터 파싱됨), 내장 엔진의 render-verdict 정책은 warn 또는 info로 보고하도록 첨부하여 빌드 안에서 테스트합니다. .wasm을 직접 빌드한 플러그인의 경우 aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json이 그 파일로 플러그인을 실행합니다. 아무것도 첨부되지 않은 역할도 소스와 설정이 없는 첨부가 받을 페이로드로 기록되므로, 정책을 첨부하기 전에 작성할 수 있습니다. 각 역할은 <role>.json(annotation-transform, label-transform, ir-verdict, render-verdict)에 기록됩니다. 한 역할의 첨부들이 서로 다른 페이로드를 받는 경우(하나가 자체 소스나 설정을 지니거나, 변환이 다음 첨부가 읽는 내용을 바꾸는 경우)에는 대신 각각이 <role>.<position>.<plugin>.json에 기록됩니다. position은 워크스페이스 구성에 나열된 순서대로 해당 역할의 첨부를 1부터 센 값이고, plugin은 플러그인 참조에서 버전을 뺀 마지막 세그먼트이며, 파일 이름에 쓸 수 없는 문자는 이스케이프됩니다. 디렉터리에 이미 있는 같은 이름의 파일은 교체되며 그 밖의 것은 건드리지 않습니다. 파일은 빌드가 끝나든 중단되든 기록되며, 어떤 역할이 실행되기 전에 중단된 빌드는 파일을 쓰지 못한 각 역할을 알려 줍니다. 이 파일을 요청해도 아티팩트나 판정은 바뀌지 않습니다. —dry-run과 함께 사용할 수 있으며, 그 경우 이 파일들만 쓰고 그 밖에는 아무것도 쓰지 않습니다. 출력 디렉터리와 lockfile은 변경되지 않습니다 |
--progress | false | stderr가 터미널이 아닐 때도 빌드 진행 표시를 강제로 켜서, 각 단계가 완료될 때마다 소요 시간과 함께 일반 텍스트 한 줄을 출력합니다. 기본값은 auto입니다. 대화형 단계 체크리스트는 stderr가 이스케이프 시퀀스를 해석하는 터미널일 때만 표시되고, 해석하지 않는 터미널에는 동일한 일반 텍스트 줄이 출력되며, 리디렉션되거나 파이프된 출력에는 아무것도 출력되지 않습니다. —quiet와 —debug는 모두 —progress보다 우선합니다 |
--quiet | false | stderr의 빌드 진행 표시를 끕니다. stdout에는 영향을 주지 않습니다. —progress보다 우선합니다 |
--release | — | Release YAML 파일의 경로입니다(필수). 상대 경로는 워크스페이스 루트가 아니라 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 해당 디렉터리가 어떤 워크스페이스에도 속하지 않고 루트도 지정되지 않은 경우, 절대 경로는 Release 자체의 폴더에서 워크스페이스를 찾습니다 |
--trace | false | 사후 검사를 위해 워크스페이스 루트 아래 dist/ 옆의 .trace/에 노드별 중간 파일을 씁니다 |
--trace-unredacted | false | 민감하다고 선언된 값을 대신하는 |
--unredacted | false | 작성자가 민감하다고 선언한 값을 제외하지 않고 출력합니다. 그러면 출력이 도달하는 모든 곳(터미널, 파이프, 파일, 화면 녹화)에 해당 값이 평문으로 담깁니다. —ir-graph가 쓰는 그래프에만 영향을 미치므로 —ir-graph가 필요합니다. .trace/ 파일에는 대신 —trace-unredacted를 사용합니다 |
--upgrade | false | auto-pull 단계를 전체 새로 고침으로 만듭니다. 기존 lockfile을 폐기하고, 기존 고정을 유지하는 대신 각 의존성을 사용 가능한 가장 높은 버전으로 올려 현재 레지스트리 상태에서 모든 의존성을 다시 해석합니다. —auto-pull을 포함합니다. 단독으로 사용하면 빌드 전에 전체 새로 고침 pull을 실행합니다. 대상을 받지 않으므로 하나의 의존성으로 좁힐 수 없습니다. 단일 고정을 채택하거나 제거하려면 대신 aggrega pull —upgrade —release |
--verify-determinism | false | 모든 노드를 두 번 렌더링하고 내보낸 바이트를 비교하여, 어떤 노드의 두 렌더링이라도 다르면 빌드를 중단합니다. 기본값은 꺼짐입니다. provider가 결정적으로 렌더링하는지, 즉 동일한 입력이 바이트 단위로 동일한 출력을 내는지 확인하는 데 사용합니다. GitOps diff와 바이트 단위 동일 출력 보장이 이에 의존합니다 |
--yes | false | 비대화형 사용을 위해 —upgrade 확인에 미리 응답합니다. 영향은 그 하나의 프롬프트에만 미칩니다. 새로 고침을 하지 않는 빌드는 아무것도 묻지 않으므로, 이 경우 이 플래그를 전달해도 동작이 바뀌지 않습니다 |