aggrega inspect
aggrega inspect는 모든 Aggrega 엔터티를 사람이 읽을 수 있는 형태로 렌더링합니다. 카탈로그 Component, 작성된 엔터티 파일, 레지스트리에 게시된 엔터티, 완전히 해석된 Release가 모두 대상입니다. 이 명령은 컴파일러가 무엇을 생성할지 이해하기 위한 표준 디버그 수단입니다. 어떤 Components가 어떤 베이스를 확장하는지, 각 타입에 어떤 Recipe가 매핑되는지, 각 노드에 어떤 Features가 연결되는지, 그리고 각 Feature의 기여가 정확히 어디에서 왔는지를 보여 줍니다.
각 엔터티 종류에는 자연스러운 “계약” 뷰가 있습니다. inspect는 그 계약을 보여 줍니다. Component가 게시하는 스키마, Manifest가 선언하는 매핑, Aggregate가 구성하는 토폴로지, Release가 해석한 노드별 Feature 연결이 그것입니다. 튜토리얼과 개념 자료는 다른 곳에 있으며, inspect는 “이 엔터티는 실제로 무엇으로 해석되는가?”라는 질문에 답합니다.
단일 위치 인수는 내용의 형태에 따라 라우팅되며, 하위 명령은 필요하지 않습니다. 명령은 다음 휴리스틱에 따라 분기합니다.
| 식별자 형태 | 분기 | 출력 |
|---|---|---|
./, ../ 또는 /로 시작하거나 .yaml / .yml로 끝남 | 파일 분기 | 파일의 kind: 헤더를 기준으로 한 파일별 검사입니다. |
oci://로 시작함 | 레지스트리 분기 | 해당 좌표에 게시된 엔터티를 레지스트리에서 읽어, 같은 종류의 파일이 받는 뷰로 렌더링합니다. 게시된 엔터티 읽기를 참조하십시오. |
| 그 밖의 모든 경우 | 카탈로그 분기 | 모든 엔터티 종류에 걸쳐 카탈로그 검색 스택에서 식별자를 조회하고, extends: 체인을 해석한 뒤, 일치한 종류 고유의 뷰를 렌더링합니다. |
세 가지 상세 수준
--list, 기본값, --detail은 모든 종류가 따르는 일관된 3단계 상세도 체계를 이룹니다. --list와 --detail은 상호 배타적이며, 둘을 함께 전달하면 조용히 해석되지 않고 거부됩니다.
--list— 식별자만 표시합니다. Component는 자신의 이름과 uses 소켓 이름을 나열하고, MappingLibrary는 매핑 이름을 나열하며, Aggregate는 구성 요소 이름을 해당 타입과 함께 나열합니다.- 기본값 — 대화형 사용에 맞춘 구조화된 개요입니다. 엔터티의 식별 정보로 시작하며, Manifest와 Release를 제외한 모든 종류에서는 엔터티가 설명을 작성한 경우 그 설명이 이어집니다. 설명이 없는 엔터티는 빈 줄을 출력하지 않고 아무것도 출력하지 않습니다. 나머지 형태는 종류별로 다릅니다. Component는 스키마와 소켓을 보여 주고, Aggregate는 구성 요소, 그 값과 각 연결이 지닌 부착 항목이 포함된 에지, 그리고 의존성 그래프를 보여 주며, Release는 경계별 노드 트리를 Feature 부착 항목과 함께 보여 주는데, 연결에 작성된 각 부착 항목은 해당 연결 아래에 나열됩니다.
--detail— 필드 본문 전체를 표시합니다. 해당 종류가 지닌 모든 것을 보여 줍니다. Component는 자체 주입 메커니즘, 필수 Features, 레이블을 추가하고, MappingLibrary는 각 매핑의 전체 템플릿 본문을 펼치며, Recipe는 워크로드 본문, provides, 어서션을 추가합니다.
일부 종류는 이 수준들을 사용해 작성된 본문을 단계적으로 더 많이 드러냅니다. MappingLibrary는 --list에서 매핑 이름을 보여 주고, 기본 수준에서 각 매핑의 합성된 사용 예를 추가하며, --detail에서 전체 템플릿 본문을 펼칩니다.
해석: --raw와 --resolved
각 kind에는 고유한 기본 해석 깊이가 있습니다(아래 표 참조). --raw와 --resolved는 언제나 사용할 수 있는 재정의 옵션이며, 서로 배타적입니다. 둘을 함께 전달하면 조용히 처리되지 않고 거부됩니다.
- **
--raw**는 모든 해석을 생략합니다. 엔터티는 파일에서 그대로, 작성된 그대로 출력됩니다. - **
--resolved**는 해당 kind의 전체 해석 깊이를 적용합니다.
기본값이 작성된 그대로인 kind에서는 --raw가 아무 효과가 없고, --resolved는 해당 kind가 지원하는 해석을 수행합니다. 기본값이 해석된 보기인 kind에서는 --raw가 작성된 그대로를 보여 주는 우회 수단입니다.
--raw는 파일을 그대로 재현하므로, 작성자가 민감하다고 선언한 값도 작성된 그대로 나타납니다. 이는 결함이 아니라 약속된 동작입니다. 일부를 조용히 숨기는 작성된 그대로의 보기는 더 이상 작성된 그대로가 아니기 때문입니다. --raw 출력은 그 출처인 엔터티 파일과 같은 방식으로 다루십시오. --output yaml도 Release를 포함한 모든 kind에 대해 같은 방식으로 파일을 재현합니다.
Release는 두 가지 질문에 더 답하며, 각각은 고유한 플래그를 가진 별도의 문서입니다. Release가 해석된 결과인 컴파일된 그래프는 --ir-graph이고, 그 의존성 클로저는 --closure입니다. 아래의 기계 판독용 출력과 의존성 클로저: --closure를 참조하십시오.
종류별 기본값
inspect는 아래 표에 있는, 단독으로 검사할 수 있는 종류를 알고 있습니다. 카탈로그 종류는 기본적으로 작성된 그대로 렌더링됩니다. 그 파일은 자체 완결적인 계약이기 때문입니다. 인스턴스 종류는 기본적으로 해석된 뷰를 보여 줍니다. 작성된 YAML은 캐스케이드나 파이프라인의 출발점일 뿐이기 때문입니다.
| 종류 | 기본값 | “해석됨”의 의미 |
|---|---|---|
| Component | 작성된 그대로 | 파일은 자체 완결적인 계약입니다. 해석은 Manifest 바인딩을 기준으로 이루어지며 --show-implements로 드러납니다. |
| Feature | 작성된 그대로 | Component와 같습니다. |
| Recipe | 작성된 그대로 | --show-implements가 spec.implements Component 참조를 해석합니다. |
| FeatureRecipe | 작성된 그대로 | --show-implements가 spec.implements Feature 참조를 해석합니다. |
| MappingLibrary | 작성된 그대로 | 항목은 불투명한 Go 템플릿 문자열이며, 렌더링은 소비 시점에 이루어집니다. |
| SchemaLibrary | 작성된 그대로 | 항목은 소비 시점에 해석되는 재사용 가능한 스키마 및 템플릿 정의입니다. |
| WorkloadLibrary | 작성된 그대로 | 항목은 Recipe가 가져오는 재사용 가능한 Workload 본문이며, 사용 시점에 평가됩니다. |
| ArtifactLibrary | 작성된 그대로 | 항목은 Recipe가 가져오는 재사용 가능한 아티팩트 번들이며, 사용 시점에 렌더링됩니다. |
| Plugin | 작성된 그대로 | 파일은 자체 완결적인 플러그인 계약입니다. 소켓 타입, export별 기능, 런타임 제약, 서명 포인터를 담습니다. 파일 경로로, 또는 카탈로그에 대한 <pluginType>/<name> 좌표로 지정할 수 있습니다. |
| Manifest | 해석됨 | extends: 체인이 적용되고, 해석된 component 및 feature 매핑이 펼쳐집니다. |
| Aggregate | 해석됨 | 토폴로지가 구축됩니다. uses 그래프와 순서가 계산됩니다. |
| Release | 해석됨 | 전체 파이프라인이 실행됩니다. 해석, 어노테이션 확장, 가드 실행, 토폴로지 구축, IR 구축. |
kind:가 Workload인 파일은 거부됩니다. Workload는 Recipe에 포함된 형태로만 존재하며 단독으로 검사할 수 있는 엔티티가 아닙니다. Workload를 보려면 Recipe를 검사하십시오.
종류별 해석 깊이
대부분의 종류에는 파이프라인이 없으며, inspect는 파일을 읽어 렌더링합니다. 세 가지 인스턴스 종류는 의미 있는 해석을 수행합니다.
- Manifest는
extends:체인을 적용하여(파일 가져오기를 따라감) 병합된 component 및 feature 매핑을 렌더링합니다.--raw는 작성된 그대로의 파일을 보여 줍니다. - Aggregate는 토폴로지를 구축합니다. uses 그래프가 구성되고 의존성 순서가 계산됩니다. 기본 보기는 component와 그 값 및 에지를 보여 주고, 이어서 의존성 그래프를 보여 줍니다.
--raw는 작성된 서브시스템 트리를 보여 줍니다. - Release는 IR까지의 전체 컴파일 파이프라인(해석, 어노테이션 확장, 가드 실행, 토폴로지 구축, IR 구축)을 실행하고, 각 노드의 Feature 첨부와 그 출처를 포함한 경계별 노드 트리를 렌더링합니다. 그래프를 형성하는 거버넌스 첨부는 보기를 위해 건너뛰지 않고 이 파이프라인에서 실행되므로, 읽는 내용은 그 첨부가 결정한 바를 반영합니다.
label-transform첨부의 레이블은 무언가가 그에 대해 매칭되기 전에 적용되어 있으며,annotation-transform첨부가 주입한 어노테이션은 직접 작성한 어노테이션과 똑같이 Feature 첨부로 확장됩니다. 이 명령이 플러그인을 해석할 수 없는 첨부가 있으면, 그 플러그인의 결정 없이 그려진 그래프를 남기는 대신 명령이 중단됩니다. 다른 Release를 확장하는 Release는 이 보기와--ir-graph모두에서 그extends:체인이 합성한 Release, 즉 그 Release를 빌드할 때 읽는 Release로 그려지므로, 부모만 지명하는 Release는 부모의 Aggregate, Manifest, 경계를 자신의 이름 아래에 보여 줍니다. Release가 지명하는 Manifest도 그 Release가 무언가를 확장하는지와 관계없이 자체extends:체인을 통해 합성되므로, 그 Manifest가 상속한 매핑을 가진 첨부에는 빌드가 사용하는 실현이 표시됩니다.--raw는 파이프라인 없이 Release 파일을 그대로 출력합니다.--closure는 같은 Release에 대해 다른 질문을 하며 파이프라인을 전혀 실행하지 않습니다. 의존성 클로저:--closure를 참조하십시오.
별도의 깊이 플래그는 없습니다. --raw / --resolved 토글이 유일한 해석 제어이며, 각 종류의 고유한 기본값 위에 적용됩니다.
오류 동작
참조된 형제 파일을 불러오지 못하면 명령은 즉시 중단됩니다. 예를 들어 Release가 존재하지 않는 Aggregate를 가리키거나, 검색 스택에 손상된 카탈로그 엔터티가 있는 경우입니다. 명령은 부분 출력을 렌더링하지 않고 명확한 메시지와 함께 중단되며, 로드 실패에 대해서는 오류를 무시하고 계속하는 모드가 없습니다. 해석에 필요한 문서를 읽을 수 없게 되면 더 이상 해석할 것이 없기 때문입니다. 이름 해석이 로드가 거부한 카탈로그 문서 하나에서 중단되면, 메시지는 그 거부를 한 번만 알립니다. 범주와, 거부가 조건을 지정하는 경우 그 짧은 코드를 담은 머리말, 이어서 해당 문서, 그다음 문서의 문제점을 보여 줍니다. 종류의 스키마가 거부한 문서라면 해당 줄과 위반한 제약 조건을 보여 줍니다. 파일을 옮기라는 제안은 포함하지 않습니다. 카탈로그가 그 파일을 읽었기 때문에 거부된 것이기 때문입니다.
컴파일러 검사가 구성을 거부하는 Release는 렌더링되지 않고 거부됩니다. Release를 해석하면 그래프가 빌드되며, 빌드가 완성된 그래프에 대해 수행하는 검사도 여기서 동일하게 수행되고, 같은 문서를 빌드할 때 출력되는 진단이 그대로 출력됩니다. 예를 들어 대상이 소켓의 selector:를 충족하지 않는 uses: 엣지, appliesTo:가 허용하지 않는 구성 요소에 연결된 Feature 등이 이에 해당합니다. 거부 시에는 첫 번째 발견 사항에서 멈추지 않고 한 번의 실행에서 모든 발견 사항을 나열하므로, 한 번의 실행으로 수정해야 할 목록 전체를 볼 수 있습니다. 이것이 이 명령이 배포에 대해 정직하게 보고하도록 하는 부분입니다. 빌드가 거부하는 구성을 렌더링하는 뷰는 문제가 있는 작업 공간을 정상이라고 보고하게 됩니다. 아무것도 해석하지 않는 선택은 영향을 받지 않습니다. --raw, --output yaml, --closure는 그래프를 빌드하지 않고 작성한 내용을 재현하거나 해석합니다.
잠금 파일이 해석 결과와 더 이상 일치하지 않는 Release는 aggrega build가 출력하는 중단과 함께 거부됩니다. Release 옆에 잠금 파일이 있으면, Release를 해석하는 모든 선택, 즉 기본 보기, --resolved, --ir-graph, --closure는 빌드가 렌더링 전에 수행하는 드리프트 비교로 잠금 파일을 Release의 해석 결과와 대조합니다. 더 이상 일치하지 않는 잠금 파일은 빌드의 E0130 거부로 명령을 중지시킵니다. 드리프트된 모든 항목을 나열한 다음, 이를 해소하는 aggrega pull --release <release>를 제시합니다. 표준 출력에는 아무것도 기록되지 않으며 명령은 0이 아닌 코드로 종료됩니다. 현재 상태의 카탈로그로 그린 그림은 그 Release의 어떤 빌드도 렌더링하지 않는 것을 보여 주게 되기 때문입니다. --raw와 --output yaml은 단독으로는 잠금 파일도 카탈로그도 읽지 않으므로 이 대조의 대상이 아닙니다. 옆에 잠금 파일이 없는 Release는 현재 상태의 카탈로그를 기준으로 해석됩니다.
kind:를 인식할 수 없는 파일은 알 수 없는 종류와 해당 파일을 보고합니다. Workload 파일은 그 종류가 임베드 전용이라는 점을 보고하고, 그것이 임베드되는 엔터티를 알려 줍니다. 읽을 수 없는 oci:// 식별자는 그 이유를 나타내는 조건과 함께 거부됩니다. 해당 조건은 게시된 엔터티 읽기에 나열되어 있습니다.
카탈로그 해석
카탈로그 검색 스택은 계층화된 우선순위로 구성됩니다. --catalog 플래그(순서대로 앞에 추가됨)가 가장 먼저 오고, 그다음 .aggrega-config.yaml의 워크스페이스 catalog_dirs가 옵니다. 구성이 workspace.releases 아래에서 어떤 Release에 고유한 디렉터리를 지정하는 경우, 그 Release에 대해서는 해당 디렉터리가 그 자리를 대신합니다. 마지막으로 워크스페이스 루트의 catalog 디렉터리가 오며, 이 디렉터리는 무엇이 이를 지정하든 지정하지 않든 읽힙니다. catalog_dirs를 빈 목록으로 작성한 워크스페이스는 로컬 카탈로그를 전혀 읽지 않습니다. 스택은 먼저 찾은 것이 우선합니다. 엔터티 식별자를 가장 먼저 선언한 디렉터리가 그 식별자를 소유하며, 이후 디렉터리의 사본은 가려집니다. 카탈로그 분기는 이 스택에 대해 모든 엔터티 종류에 걸쳐 고정된 우선순위로 식별자를 해석하고, 첫 번째 일치 항목을 해당 종류 자체의 뷰로 렌더링합니다. 파일 분기와 릴리스 분기는 Manifest 매핑이나 extends: 부모를 해석해야 할 때 이 스택에서 참조된 카탈로그 엔터티를 로드합니다. 스택에 없는 extends: 부모는 빌드가 읽는 곳에서 읽힙니다. 즉 아티팩트 캐시에서, Release의 lockfile이 그 부모에 대해 기록한 고정(pin) 아래에서 읽힙니다. 이 lockfile은 지정된 Release의 것이거나, 아무것도 지정되지 않은 경우 워크스페이스에 있는 각 Release의 것입니다. 따라서 레지스트리에 게시된 베이스는 aggrega pull이 이를 가져와 고정한 뒤에 여기에서 해석되며, 그 전에는 명령이 aggrega pull --release <release>를 안내하며 거부됩니다. 아무것도 가져오지 않습니다.
Release의 조건으로 이름 조회하기
이름만 단독으로 주어지면 워크스페이스 자체의 스택에서 조회됩니다. 그 옆에 --release <release-path>를 지정하면 이름은 대신 해당 Release의 스택에서 조회됩니다. 이 스택은 워크스페이스 구성이 그 Release에 지정한 디렉터리에 --catalog를 앞에 추가한 것으로, 해당 Release의 빌드가 읽는 것과 같습니다. 따라서 Release마다 카탈로그 변형을 하나씩 두고 각각 같은 엔터티를 선언하는 워크스페이스는, 이름에 대해 해당 Release가 빌드에 사용하는 변형으로 응답합니다.
aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml해당 Release의 스택이 해석하지 못하는 이름은 거부되며, 로컬 엔터티를 어디에서 읽는지에 대한 설명에는 그 Release의 workspace.releases 아래 항목이 명시됩니다. 조회가 읽은 것이 바로 그 항목이기 때문입니다. --release는 이름을 조회할 스택을 선택하므로 이름에만 적용됩니다. 파일 경로와 레지스트리 참조는 있는 그대로 읽히며 이 플래그를 거부합니다. 존재하지 않는 파일이나 디렉터리를 지정한 --release는 조회가 시작되기 전에 거부됩니다.
게시된 엔터티 읽기
aggrega inspect oci://<host>/<repository>:<tag>는 해당 좌표에 게시된 엔터티를 읽습니다. :<tag> 대신 @<digest>를 쓰면 하나의 매니페스트를 정확히 지정합니다. 레지스트리에만 존재하는 엔터티를 살펴보는 방법이 바로 이것입니다. Catalog and Registry §6에서 설명하듯 저장소는 종류 세그먼트 뒤에 엔터티의 식별자가 오는 형태이며, aggrega push는 게시한 참조를 출력하는데, 여기서는 그 앞에 oci://를 붙여 읽습니다.
보이는 것은 게시된 그대로의 엔터티입니다. 선언한 파일과 함께 게시된 엔터티(로컬 차트나 잠금 파일을 가진 Recipe, 스키마를 가져오는 Component)는 아카이브로 배포되며, 엔터티는 그 아카이브에서 풀어냅니다. 즉 아카이브 루트에 있으면서 게시 가능한 종류를 선언하는 문서를 꺼내므로, 함께 배포된 차트 템플릿이나 compose 조각을 엔터티로 오인하지 않습니다. 파일을 선언하지 않은 엔터티는 문서 그대로 배포되며, Plugin의 엔터티는 함께 게시된 실행 파일이 아니라 매니페스트에서 읽습니다. 그런 다음 문서는 같은 종류의 파일과 동일한 뷰로 렌더링되며, 동일한 상세 수준과 동일한 --raw 및 --output yaml을 사용합니다. 상속은 적용되지 않습니다. 뷰는 게시자가 해당 좌표에 둔 내용 그대로입니다. 읽기 쉬운 레이아웃은 읽은 내용으로 끝납니다. 즉 좌표, 엔터티를 아카이브로 담았는지 문서 자체로 담았는지, 매니페스트가 선언한 미디어 유형, 그리고 해당 매니페스트의 다이제스트이며, 이 다이제스트를 :<tag> 대신 @<digest>로 쓰면 같은 바이트를 다시 읽습니다. --output yaml은 문서만 출력하고 그 뒤에는 아무것도 출력하지 않습니다.
검사하는 것과 검사하지 않는 것. 가져온 바이트는 아티팩트 자체의 매니페스트가 기록한 다이제스트와 대조하여 검사되며, 이로써 해당 매니페스트가 지정한 바이트임이 확인됩니다. 이는 사전에 기록된 무언가가 아니라 레지스트리가 제공한 내용에 대한 검사입니다. 아티팩트에 첨부된 서명은 검증하지 않으며, 아티팩트에 기록된 철회도 보고하지 않습니다. 아무것도 기록하지 않으므로(캐시 항목도 잠금 파일도 없음), 좌표를 읽어도 이후 빌드가 해석하는 내용은 전혀 바뀌지 않습니다.
네트워크에 접속합니다. 레지스트리에는 이 머신이 해당 레지스트리에 대해 보유한 자격 증명으로 접속하며, 이 자격 증명은 aggrega push와 aggrega pull이 읽는 것과 같은 저장소에서 가져옵니다. 이 머신에 있는 레지스트리에는 일반 HTTP로 접속합니다. 오프라인 워크스페이스는 접속을 시도하기 전에 읽기를 거부합니다.
응답할 수 없는 읽기는 0이 아닌 코드로 종료하며 표준 출력에 아무것도 출력하지 않습니다. 아래의 각 실패는 조건과 함께 대처 방법을 알려 줍니다. 레지스트리에 전혀 연결할 수 없는 경우에는 읽기를 중단시킨 네트워크 오류가 보고됩니다.
| 발생한 상황 | 조건 |
|---|---|
| 참조 아래에 게시된 것이 없음 | E0137 |
| 레지스트리가 자격 증명을 거부했거나, 해당 레지스트리에 저장된 자격 증명이 없음 | E0138 |
| 워크스페이스가 오프라인 상태임 | E0125 |
| 아티팩트가 풀 수 없는 아카이브임 | E0300 |
| 아카이브 루트에 엔터티 문서가 없음 | E0298 |
| 아카이브 루트에 엔터티 문서가 둘 이상 있음 | E0299 |
| 문서가 레지스트리가 게시하는 종류의 엔터티가 아님 | E0301 |
각 코드는 오류 참조에 나열되어 있습니다. 저장소를 지정하지 않거나 태그와 다이제스트 중 어느 것도 지정하지 않은 참조는 대신 써야 할 형식과 함께 거부됩니다. 레지스트리가 게시하는 종류 중 Release는 없으므로 --ir-graph와 --closure는 아무것도 가져오기 전에 거부됩니다.
사용 중단 및 철회 알림
게시자는 아티팩트를 게시한 후 해당 아티팩트에 대해 마커를 기록하여, 게시된 버전이 사용 중단되었거나 철회되었음을 명시할 수 있습니다. 카탈로그 분기가 엔터티를 해석할 때 inspect는 그러한 마커를 엔터티 자체 뷰 아래에 보고합니다. 이는 Component에만 해당하지 않고, 이름으로 해석하는 모든 종류에 해당합니다.
알림에는 게시자가 기록한 심각도(warning, error 또는 retracted)와 함께 마커가 기록된 버전, 사유, 대체 항목이 지정된 경우 그 대체 항목, 그리고 발행 날짜가 표시됩니다. 세 가지 심각도는 모두 보고됩니다. 이는 빌드가 해석하는 결과를 바꾸는 집합보다 넓습니다. retracted로 표시된 버전은 버전 선택에서 제외되지만, warning과 error는 권고 사항일 뿐이며 여전히 선택됩니다. inspect는 게시자가 밝힌 내용을 보여 줄 뿐, 무엇을 받게 될지 결정하지 않습니다.
알림은 엔터티가 해석되는 레지스트리의 로컬 인덱스에서 읽으며, 이 인덱스는 aggrega registry update가 빌드합니다. 따라서 네트워크가 필요 없으며 오프라인 워크스페이스에서도 동작합니다. 인덱스는 스냅숏이므로, 알림은 마지막에 해당 스냅숏을 만든 시점을 밝히고 이를 갱신하는 명령을 알려 줍니다. 인덱스가 빌드되지 않은 워크스페이스는 아무것도 보고하지 않으므로, 알림이 없다는 것은 “기록된 것이 없음”이 아니라 “이 스냅숏에 기록된 것이 없음”을 의미합니다.
마커는 자체 서명이 레지스트리의 신뢰 정책이 인정하는 서명자에 대해 검증될 때만 보고됩니다. 서명되지 않은 마커나 서명이 검증되지 않는 마커는 보고되지 않습니다. 인증할 수 없는 주장은 사실로 제시하지 않습니다.
알림은 사람이 읽을 수 있는 뷰에만 함께 표시됩니다. --output yaml과 --ir-graph는 모두 알림을 덧붙이지 않으므로, 둘 중 하나를 파싱하는 소비자는 문서만 받습니다.
실습 예제
카탈로그 Component 조회
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"기본 보기는 Component가 설명을 작성한 경우 그 설명을 먼저 표시하고, 이어서 해석된 스키마(extends: 병합 이후)와 선언된 uses-socket을 표시합니다. 위의 Component는 설명을 작성하지 않았으므로 출력이 곧바로 스키마부터 시작합니다. --detail은 self-inject 메커니즘, 필수 Features, 레이블을 추가하고, --list는 Component 식별자와 소켓 이름만 표시합니다.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observability--show-implements를 사용한 Recipe
Recipe의 기본 보기는 선언한 입력 모드마다 하나의 섹션과 그 기능(capability), 값 매핑을 표시합니다. --show-implements는 spec.implements 참조를 카탈로그에서 해석하여 바인딩된 Component를 해당 Component가 요구하는 첨부(attachment)와 함께 렌더링합니다:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metrics여러 입력 모드를 선언하는 Recipe
Recipe의 입력 모드는 더하기 방식으로 조합됩니다. 렌더링할 source:, 합성할 workload:, artifacts: 맵은 각각 출력을 제공하며, Recipe는 이들을 어떤 조합으로든 선언할 수 있습니다. inspect는 하나를 골라내지 않고 Recipe가 선언한 모든 모드를 보고하므로, 표시되는 내용은 작성한 그대로의 집합입니다:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yaml섹션은 source: → workload: → artifacts: 순서로 정렬됩니다. 이는 빌드가 Recipe를 단일 모드 이름으로 해석할 때, 그리고 바인딩된 provider가 지원하지 못하는 선언된 모드를 보고할 때 적용하는 순서와 같으므로, 이 보기와 빌드의 진단은 모드를 같은 순서로 나열합니다. source:와 workload:를 모두 선언하지 않은 Recipe는 artifacts 전용으로 보고되며, 이것이 보기가 단일 모드를 표시하는 유일한 경우입니다.
Manifest(기본적으로 해석됨)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)기본 보기는 Manifest의 extends: 체인을 적용하고, 해석된 component 및 feature 매핑과 어노테이션 바인딩을 나열합니다. --raw는 extends 해석 이전의, 작성된 그대로의 파일을 표시합니다.
Aggregate(기본적으로 해석됨)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontend기본 보기는 토폴로지를 구축하고 각 component를 그 값 및 uses-edge와 함께 표시한 뒤, 계산된 의존성 그래프를 표시합니다. 하위 시스템 트리는 중첩되어 렌더링되며, --flat은 노드마다 하나의 섹션을 전체 점 표기 경로를 키로 하여 렌더링합니다.
긴 형식으로 작성된 연결 뒤에는 그 연결이 전달하는 첨부가 이어지며, 각 첨부는 소비하는 component에서 갖는 이름(연결의 별칭과 슬롯을 점으로 이은 것) 아래에, 그것이 지정하는 Feature 타입과, 채우는 슬롯 및 선언된 민감 자료를 다루는지 여부를 나타내는 절과 함께 표시됩니다:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]슬롯과 표시는 이 Aggregate를 배포하는 Release의 빌드가 해당 첨부에 대해 기록하는 사실이며, Release 보기와 같은 방식으로 읽습니다(첨부 연결, 슬롯 및 민감도 절 참조). 이들은 소켓의 슬롯 선언과 Feature 자체의 선언에서 오므로, 어떤 Release가 Aggregate를 배포하는지에 좌우되지 않습니다. Aggregate는 Manifest를 지정하지 않으므로, Release의 Manifest가 첨부에 대해 선택하는 구현은 여기에 표시되지 않습니다. 이 보기는 component의 연결과 그 연결이 전달하는 것을 나열하며, component 자체 블록의 첨부는 Release 보기에 나타납니다.
Release(기본적으로 해석됨)
Release 보기는 가장 중요한 검사입니다. 전체 파이프라인을 실행하고, 경계(boundary)마다 모든 Component 노드와 그 uses-edge, 그리고 해당 노드에 첨부된 모든 Feature(연결에 작성된 것은 그 연결의 edge 아래)를 렌더링하며, 각각에 대해 채우는 첨부 슬롯, 선언된 민감 자료를 다루는지 여부, 그것을 구현하는 FeatureRecipe와 함께, 첨부가 어디에서 왔는지 보여주는 출처 괄호를 표시합니다:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)각 경계는 출력 디렉터리와 provider가 소비하는 어노테이션을 가지며, 경계 아래의 각 component는 Aggregate component 타입, uses-edge(경계를 넘는 edge는 표시됨)와 각 edge 뒤에 그 연결이 전달하는 첨부, 그리고 자체 Feature 첨부를 가지며, 모든 첨부에는 사실 절과 출처 괄호가 붙습니다. --flat은 경계 트리를 전체 경로를 키로 하여 경계마다 하나의 섹션으로 축약합니다. --raw는 파이프라인 없이 Release 파일을 그대로 출력합니다.
YAML 출력
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}카탈로그에서 이름으로 지정한 Component는 카탈로그가 해석한 엔터티로 출력되므로, extends: 병합 후에는 작성된 파일이 아니라 병합된 엔터티를 보게 됩니다. Component 파일은 작성된 그대로 출력됩니다.
기계 판독 가능한 출력
기계 판독 가능한 출력을 생성하는 플래그는 두 가지이며, 각각 서로 다른 질문에 답합니다. --output은 이 명령이 이미 렌더링하는 문서의 형식을 선택하고, --ir-graph는 그에 더해 다른 문서, 즉 Release가 해석되어 만들어지는 컴파일된 그래프를 요청합니다. 두 플래그는 서로 독립적입니다. 둘을 함께 전달하면 그래프와 작성된 그대로의 YAML을 각각 한 번씩 얻습니다.
--output yaml은 엔터티를 작성된 그대로 출력하므로 파이프 처리와 diff에 적합합니다. 이 출력은 원문 그대로이며, 작성자가 민감하다고 선언한 값도 포함됩니다. 입력을 재현한다고 주장하는 출력은 그 일부를 숨기면서 여전히 재현한다고 할 수 없기 때문입니다. 이 출력은 원본 엔터티 파일과 같은 방식으로 파이프 처리하고, 저장하고, 공유하십시오.
컴파일된 그래프: --ir-graph
aggrega inspect <release> --ir-graph는 실행이 해석한 그래프를 JSON으로 표준 출력에 기록하며, 명령이 어차피 렌더링하는 뷰보다 앞서 출력합니다. JSON 문서 하나와 끝의 줄바꿈 하나이므로, 스트림을 디코딩하는 소비자는 그래프를 읽고 멈춥니다.
이 플래그는 그래프로 해석되는 유일한 종류인 Release에 적용됩니다. 다른 종류나 이름으로 지정한 카탈로그 엔터티에 대해 요청하면, 명령은 해당 엔터티 자체의 뷰를 렌더링하면서 요청을 조용히 버리는 대신 요청을 거부하고 그 사실을 알립니다.
컴파일러의 검사가 거부하는 구성은 그래프를 생성하지 않습니다. 오류 동작에서 설명하는 거부는 이 스트림에 무언가가 기록되기 전에 일어나므로, 스트림을 읽는 파이프라인은 같은 문서의 빌드라면 거부했을 그래프를 받지 않습니다. 대신 빌드가 보고할 것과 같은 결과와 0이 아닌 종료 코드를 받습니다.
같은 플래그가 같은 의미로 aggrega build와 aggrega validate에도 있습니다. 각 명령은 해당 명령이 생성하는 다른 결과에 더해, 그 실행이 계산한 그래프를 돌려줍니다. 편집기 통합은 데몬의 프로토콜을 통해 같은 그래프를 읽습니다.
--output yaml은 그래프를 출력하지 않습니다. 다른 모든 종류에서와 똑같이, 작성된 Release를 재현합니다. 그래프가 필요한 파이프라인은 대신 --ir-graph에서 그래프를 읽으며, YAML이 아닌 JSON을 받습니다.
그래프는 값을 숨깁니다. 그래프는 누군가 작성한 파일이 아니라 컴파일이 Aggregate, Release, 카탈로그로부터 계산한 결과이므로, 지켜야 할 작성 그대로의 계약이 없으며, 읽기용 레이아웃을 지배하는 것과 같은 선언이 그래프에도 적용됩니다. 그래프에 작성자가 민감하다고 선언한 리프가 있으면, 그 값은 숨겨졌음을 나타내는 단일 키 객체로 대체됩니다.
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}키는 남으므로, 그래프는 노드와 그 연결 항목이 어떤 리프를 가지는지 여전히 알려 줍니다. 사라지는 것은 값뿐입니다. 같은 페이로드에서 선언되지 않은 형제 항목은 작성된 그대로 출력됩니다. 위의 secretName은 작성자가 선언하지 않은 공개 위치 지정자이므로 출력됩니다. 표시자와 함께 나오는 사유는 값이 없는 이유를 알려 줍니다. 선언이 적용되는 리프는 declared이고, 페이로드가 이 명령이 읽을 수 없는 형태로 도착한 경우는 unreadable이며, 이 경우 일부를 추측하는 대신 페이로드 전체가 숨겨집니다.
연결 자체의 구성도 같은 방식으로 숨겨집니다. Aggregate가 uses 항목에 작성하는 연결별 values와 Release가 그 항목에 작성하는 연결별 infra는 소비하는 컴포넌트의 소켓, 즉 그 소켓이 선언하는 valueSchema와 infraSchema(해당 구성을 검증하는 기준이 되는 계약)가 결정하며, 대상의 선언이 결정하는 일은 없습니다. 어느 한 계약이 sensitive: true로 선언한 리프는 에지의 values와 infra에서, 그리고 작성자가 작성한 그대로 값을 담고 있는 소비 노드의 uses 항목에서 마커로 대체됩니다. 각 에지는 숨긴 리프를 sensitive_payload_leaves 아래에 나열하며, 이는 노드가 자신의 리프에 사용하는 필드입니다. 소켓이 읽을 수 있다고 선언한 연결에 있는 같은 이름의 리프는 작성된 그대로 출력됩니다.
파이프라인에 값이 정말로 필요한 경우 --unredacted를 전달하고, 그 출력은 엔터티 파일 자체를 다루듯 다루십시오. aggrega build와 aggrega validate도 --ir-graph와 함께 같은 조건으로 같은 플래그를 받습니다. 이 플래그를 전달하지 않으면 이들이 돌려주는 그래프는 값을 숨깁니다.
데몬의 프로토콜도 같은 규칙에 따라 같은 그래프를 제공합니다. aggrega/irGraph는 이러한 값을 숨긴 채 응답하며, 이 플래그의 프로토콜 표기인 unredacted 필드를 설정한 요청에만 값을 그대로 반환합니다. 따라서 편집기 패널이 그리는 내용도 같은 선언을 따르며, 값을 표시하는 클라이언트는 그 값을 요청했기 때문에 표시하는 것입니다.
의존성 폐포: --closure
aggrega inspect <release> --closure는 Release의 의존성 폐포를 보고합니다. 이는 Release가 도달하는 모든 카탈로그 엔터티와 각각이 해석된 버전, 그리고 두 포인터가 해석된 Aggregate 및 Manifest의 식별자와 그 엔터티들이 참조하는 공유 문서를 함께 담습니다. 아무것도 렌더링되지 않으며 아티팩트도 생성되지 않습니다. 폐포는 빌드되는 것이 아니라 해석되는 것이므로, 이에 답하기 위해 provider를 로드하지 않습니다.
폐포와 해석된 뷰는 서로 다른 문서이며, 어느 쪽도 다른 쪽에서 복원할 수 없습니다. 해석된 뷰, 즉 이 명령이 Release에 대해 기본으로 렌더링하는 것은 배포가 어떤 모습인지를 말합니다. 경계, 컴포넌트 노드, 무엇이 무엇에 연결되어 있는지, 각 노드에 무엇이 붙어 있는지입니다. 폐포는 그것을 빌드하기 위해 무엇을 어떤 버전으로 가져왔는지를 말합니다. 엔터티는 노드로 한 번도 나타나지 않고도 도달될 수 있습니다. Manifest가 컴포넌트 타입을 매핑하는 Recipe는 모든 빌드에서 도달되지만 어느 빌드에서도 노드가 아닙니다. 또한 노드는 선언된 컴포넌트 타입을 기록할 뿐, 그 타입이 해석된 버전은 기록하지 않습니다. 따라서 “이 버전은 왜 바뀌었는가?”, “이 공유 문서를 바꾸면 무엇에 영향을 주는가?”, “이 배포는 실제로 무엇에 의존하는가?”를 묻는 독자는 폐포를 요청하는 것이며, 해석된 뷰를 가진 독자가 그것을 더 열심히 읽는다고 해서 이미 폐포를 가진 것은 아닙니다.
같은 단어는 모든 인터페이스에서 같은 문서를 요청합니다. 여기의 --closure, 데몬 프로토콜의 aggrega/releaseClosure(aggrega serve의 “클로저는 그래프가 아닙니다” 참조), 어시스턴트 도구 프로토콜에서 describe 도구의 release 모드는 모두 Release에 대한 이 질문에 답합니다. 어느 쪽에서든 Release 이름은 같은 해석에 도달하므로, 세 가지가 Release의 의존 대상에 대해 서로 다른 답을 내는 일은 없습니다. Release가 해석되는 결과와 더 이상 일치하지 않는 lockfile에 대해서는 이 명령과 describe 도구가 빌드의 드리프트 중단으로 거부하며, 편집 중인 편집기를 지원하는 데몬은 응답합니다.
하나의 문서이므로 단독으로 요청합니다. --closure는 해석된 뷰 대신 폐포를 선택하며, --raw, --resolved, --output, --ir-graph와 함께 쓸 수 없습니다. 이들은 각각 같은 Release에 대한 다른 문서를 요청하며, 두 요청을 받아들이는 명령은 그중 하나에만 조용히 답해야 하기 때문입니다. 조합하면 해당 쌍을 명시하며 거부됩니다.
Release에만 적용되며 그 밖의 대상에는 적용되지 않습니다. 카탈로그 엔터티, Aggregate 파일, Manifest는 어느 것도 폐포를 해석하지 않으므로, 요청은 해당 대상의 자체 뷰를 렌더링하고 요청을 버리는 방식으로 답하지 않고 거부됩니다. 버려진 요청은 호출자에게 폐포가 비어 있는 대상과 똑같이 보이기 때문입니다.
각 결과는 구별됩니다. 해석되는 Release에는 목록으로 답합니다. 파일을 가리키지 않는 Release 경로는 파일이 없다고 알리며 거부됩니다. 존재하지만 폐포를 해석할 수 없는 Release는 무엇을 해석할 수 없었는지와 그 참조가 어디에서 왔는지를 알리며 거부되고, 이어서 카탈로그 로드가 거부한 파일이 있으면 나열합니다. 거부된 파일은 Release가 도달하는 엔터티가 누락되는 일반적인 원인이기 때문입니다. Release 옆에 있는 플러그인 신뢰 기록이 존재하지만 읽을 수 없으면 무엇을 읽을 수 없었는지를 알리며 거부됩니다. 이를 건너뛴 목록은 아무것도 확인할 수 없었던 곳에서 철회된 플러그인이 없다고 보고하게 되기 때문입니다. lockfile이 더 이상 해석 결과와 일치하지 않는 Release는 오류 동작에서 설명하듯 빌드가 출력하는 드리프트 중단과 함께 거부됩니다. 나열되는 버전이 그 Release의 어떤 빌드도 사용하지 않는 버전이 되기 때문입니다. 어느 경우에도 빈 목록으로 답하지 않습니다. 빈 목록은 잘못 입력한 경로나 손상된 워크스페이스를 아무것에도 의존하지 않는 Release로 보고하게 되기 때문입니다.
세 가지 상세 수준은 모든 종류에서와 같이 적용됩니다. --list는 파이프 처리를 위해 참조만 한 줄에 하나씩 출력합니다. 기본 수준은 여기에 해석된 식별자, 각 참조가 해석된 버전, 참조된 공유 문서, 대상이 매핑된 타입을 구현하지 않는 Manifest 매핑, 그리고 Release가 의존하는 대상에 기록된 지원 중단 또는 철회 공지(잠금 파일에서는 고정된 참조에 대해, 그 옆의 플러그인 신뢰 기록에서는 수락 또는 거부 판정을 반환하는 역할로 연결된 플러그인에 대해 기록된 것)를 aggrega build가 같은 마커에 대해 출력하는 문구 그대로 추가합니다. --detail은 참조 위치가 종류를 기록한 경우 각 참조의 종류를 추가합니다. 문서의 어떤 위치는 가리키는 종류를 명시하고 어떤 위치는 그렇지 않으므로, 종류는 이름의 형태로 추측하지 않고 알려진 경우에만 보고됩니다.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)워크스페이스가 Release가 해석되는 버전을 기록해 둔 경우, 그 기록이 해석의 시작점이 되므로 보고되는 버전은 카탈로그에 오늘 우연히 있는 버전이 아니라 이 배포가 실제로 빌드되는 버전입니다. 그러한 기록이 없는 워크스페이스는 현재 상태의 카탈로그를 기준으로 해석합니다.
첨부의 연결, 슬롯 및 민감도 절
Release 뷰의 각 Feature 첨부에는 컴파일러가 첨부 자체에 대해 기록하는 사실을 나타내는 절이 붙습니다. 이 절은 첨부가 채우는 첨부 슬롯, 선언된 민감 자료를 다루는지 여부, 첨부를 실현하는 FeatureRecipe를 나타내며, 컴포넌트의 연결 중 하나에 작성된 첨부의 경우 그 첨부가 작성된 연결도 나타냅니다. 이 절은 첨부 이름과 출처 괄호 사이에 위치하며, 아래의 두 출처 형식에서 동일하게 표시됩니다.
연결에 작성된 첨부는 Features: 아래가 아니라 Uses:에 있는 해당 연결 줄 아래에 나열되므로, Features:에는 컴포넌트 자체의 첨부만 담깁니다. 그 위의 줄은 연결을 별칭과 연결이 도달하는 컴포넌트로 나타내며, 나머지는 첨부 자체의 절이 나타냅니다.
[socket: <socket>]— 연결이 연결된 소켓으로, 연결 줄에는 나타나지 않습니다. 이 항목은 나머지를 읽는 방식을 바꾸므로 절의 맨 앞에 옵니다. 뒤따르는 슬롯 부분은 컴포넌트가 자체 첨부를 위해 선언한 슬롯이 아니라 연결의 소켓이 선언한 슬롯을 나타냅니다.[connection: <alias> through socket <socket>]—Uses:블록에 연결 줄이 표시되지 않는 첨부에 대한 같은 사실로, 이런 첨부는Features:아래에 나열되고 연결을 여기에서 나타냅니다. 어느 쪽이든 연결은 첨부당 한 번만 나타나며, 두 번 나타나지 않습니다.[slot: <name>]— 첨부가<name>이라는 슬롯을 채웁니다. 슬롯은 슬롯 자체의 이름으로 Feature를 첨부하여 채우므로,<name>은 첨부가 작성된 이름이며 선언된 슬롯과 대조됩니다. 대조 대상은 호스트 Component 자체의 첨부에 대해서는 그 Component의featuresSchema이고, 연결에 작성된 첨부에 대해서는 연결의 소켓이 선언한featuresSchema입니다.[free]— 첨부가 선언된 슬롯을 채우지 않습니다. 즉, 해석된 Component가 그 이름의featuresSchema슬롯을 선언하지 않습니다. 이는 진단이 아니라 발견 사항입니다. 자유 형식 첨부는 허용되며, 이를 금지하려는 운영자는 도구가 거부해 주기를 기대하는 대신 거버넌스 정책으로 표현합니다.[sensitive]— 첨부된 Feature가 민감한 리프를 선언하거나, 첨부가 채우는 슬롯이sensitive: true를 선언하거나, 또는 둘 다이기 때문에, 첨부가 작성자가 민감하다고 선언한 자료를 다룹니다.[realization: <name>:<version>]— Release의 Manifest가 첨부에 바인딩하는 FeatureRecipe입니다. Manifest가 첨부 자체의 이름을 매핑하는 경우 그 이름으로(연결에 작성된 첨부의 경우 별칭과 슬롯을 점으로 이은 이름), 그렇지 않으면 Feature 타입으로 바인딩됩니다. 이는 같은 문서를 빌드할 때 첨부를 렌더링하는 실현이며, 컴파일된 그래프가 첨부에realization으로 담는 값과 같으므로(--ir-graph참조), 이 뷰와 그래프가 서로 다른 실현을 나타낼 수 없습니다. 이 항목은 절의 맨 끝에 옵니다.
여러 사실이 적용되면 하나의 절에 함께 나타납니다. core/storage/s3-object-store는 sensitive: true로 표시된 secret_access_key 슬롯을 선언하므로, 그 이름으로 첨부된 자격 증명은 두 사실을 모두 보고하고, Component가 슬롯을 선언하지 않은 이름으로 첨부된 Feature는 슬롯도 민감도도 보고하지 않습니다. 각 Feature 타입을 FeatureRecipe에 매핑하는 Manifest가 있으면 각 줄은 실현도 나타냅니다.
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]models 소켓이 sensitive: true로 표시된 credential 슬롯을 선언하고, 그 슬롯을 채우는 연결을 별칭 gpt로 연결하는 컴포넌트는, 그 첨부를 연결 아래에 나열합니다. 컴포넌트 자체의 자격 증명은 그 옆의 Features: 아래에 남습니다.
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]연결에 작성된 첨부는 [free]를 보고하지 않습니다. 소켓은 자신이 선언한 슬롯만 허용하며, 다른 이름을 담은 연결은 빌드가 로드될 때 거부됩니다.
적용되는 사실이 없으면 절 전체가 생략되며, 각 부분은 독립적으로 생략됩니다.
- 소켓 또는 연결 부분이 없음은 첨부가 컴포넌트 자체의 블록에 작성되었거나, 더 넓은 범위에서 또는 어노테이션 기반 확장으로 도달했음을 의미합니다.
- 슬롯 부분이 없음은 호스트 Component의 선언된 슬롯 집합을 해석할 수 없었음을 의미합니다. 예를 들어 그 타입이 어떤 카탈로그 엔터티와도 일치하지 않는 경우입니다. 이는 의도적으로
[free]와 구별됩니다.[free]는 “그 이름의 슬롯이 선언되지 않았다”는 답이고, 부분이 없다는 것은 그 질문에 아예 답할 수 없었다는 뜻입니다. sensitive없음은 어떤 선언도 첨부를 표시하지 않았음을 기록합니다. 이는 첨부가 비밀을 전혀 담지 않는다는 판정보다 좁은 의미입니다. 이 축은 선언을 보고하며, 필드의 이름이나 값에서 아무것도 추론하지 않습니다.- 실현 부분이 없음은 Manifest가 첨부를 카탈로그에 있는 어떤 FeatureRecipe에도 바인딩하지 않음을 의미합니다.
선언된 이름이 문자 그대로 free인 슬롯도 [free]로 렌더링되어 자유 형식 첨부와 구별되지 않습니다. 슬롯 네임스페이스에서 그 단어를 예약하는 장치는 없습니다.
IR 출처 괄호 문법
Release 보기의 각 Feature 연결에는 출처 괄호가 붙습니다. 괄호는 축약 형식(연결의 출처가 모든 리프에서 균일할 때 Feature당 괄호 하나) 또는 리프별 형식(연결의 리프가 서로 다른 출처에서 올 때 리프당 괄호 하나)을 취할 수 있습니다. 괄호 본문은 세 가지가 있으며, 두 형식 모두에 동일하게 적용됩니다.
세 가지 괄호 본문
-
[explicit]— Feature 연결이 작성자가 선언한 것입니다. Aggregate 또는 Release가 해당 노드에서 Feature를 명시적으로 지정했습니다. 명시적 연결은 우선순위가 가장 높은 출처이며, 같은 리프에서 어노테이션 기반 기여보다 항상 우선합니다. -
[annotation: <key> from <source>]— Feature 연결이 어노테이션 기반입니다.<source>의 어노테이션이 이 Feature를 선언하는 Manifest 바인딩과 일치했기 때문에 컴파일러가 이를 합성했습니다.<key>는 바인딩을 발동시킨 어노테이션 키(예:business.aggrega.ai/team)이고,<source>는 어노테이션을 지닌 엔터티(aggregate,release,component또는manifest)입니다. 합성된 연결은 구조적으로 명시적 연결과 동일하며 이후 렌더링도 둘을 같은 방식으로 처리하지만, 디버깅을 판별 가능하게 유지하도록 출처 괄호가 둘을 구분합니다. -
[explicit; overrides annotation: <key> from <source>]— 한 리프에서 작성자의 명시적 선언이, 그렇지 않았다면 같은 리프를 설정했을 어노테이션 기여를 억제할 때 발동하는 리프별 형식입니다. 양측 합성에서 이 경우가 생깁니다. 예를 들어 Aggregate 어노테이션이 Feature의values:기둥을 제공하고, Release 어노테이션이infra:기둥을 제공하며, 같은 Feature에 대한 명시적 Release 선언이 infra 리프 하나를 재정의할 수 있습니다. 리프 괄호는 명시적 작성자와 억제된 어노테이션을 모두 기록합니다. 억제된 어노테이션은 렌더링된 출력에 기여하지 않지만, 그 존재가 inspect 보기에 나타나므로 운영자는 어떤 어노테이션이 어디에서 재정의되었는지 확인할 수 있습니다.
축약 형식과 리프별 형식
컴파일러는 연결의 리프별 출처를 순회하며 균일성을 확인하여 축약 렌더링과 리프별 렌더링 중 하나를 선택합니다. 연결의 출처는 (Feature의 values: 및 infra: 기둥 전체에서) 값이 채워진 모든 리프가 같은 기원(명시적 또는 어노테이션), 어노테이션 기반인 경우 같은 어노테이션 키, 같은 출처 엔터티를 공유하고, 어떤 리프에도 “overrides annotation” 표시가 없을 때 균일합니다. 출처가 균일하면 컴파일러는 연결당 괄호 하나를 출력합니다.
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]출처가 갈라지면 — 대표적인 경우는 같은 Feature에 대해 Aggregate 어노테이션이 values:를, Release 어노테이션이 infra:를 제공하는 양측 합성입니다 — 컴파일러는 값이 채워진 리프당 괄호 하나를 출력합니다.
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]순회 순서는 values 기둥이 먼저(작성자 순서대로), 그다음 infra 기둥(같은 방식)입니다. 기둥 접두사(values. / infra.)와 기둥 안의 점 표기 경로가 각 괄호가 어떤 리프에 주석을 다는지 정확히 가리킵니다.
민감으로 선언된 값
스키마가 sensitive: true를 선언한 리프는 값 대신 고정 텍스트 <redacted>를 출력합니다. 키, 필러 접두사, 출처 괄호는 모두 유지되고 값만 대체되므로, 레이아웃은 여전히 엔터티가 어떤 리프를 가지며 각 리프가 어디에서 왔는지를 보여 줍니다. 영향을 받는 읽기용 화면은 두 가지입니다. Aggregate의 노드별 Values: 블록과, 해석된 Release의 리프별 연결 블록입니다. 후자에는 연결(connection)에 작성되어 해당 연결의 줄 아래에 출력되는 연결도 포함되며, 이 연결은 컴포넌트가 같은 Feature를 직접 가질 때 보류되는 리프와 정확히 같은 리프를 보류합니다. --ir-graph 아래의 Release 컴파일 그래프는 기계 판독용 출력에 설명된 구조화된 형식으로 같은 리프를 보류합니다.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>선언된 리프만 보류되며, 연결 수준의 [sensitive] 절은 보류 지시가 아닙니다. 이 절은 연결이 비밀 자료를 다룬다는 것을 나타낼 뿐, 어느 리프가 그 자료를 담는지는 나타내지 않습니다. 자격 증명 Feature의 게시된 위치 정보(리소스 이름과 데이터 키)는 공개 정보이며 표준 라이브러리 카탈로그에서 의도적으로 선언하지 않은 채로 두었으므로, 그렇지 않은 자료 옆에 평문으로 출력됩니다.
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]필드 이름으로부터 추론되는 것은 없습니다. 선언이 없는 password라는 필드는 값을 출력하고, 선언된 key라는 필드는 출력하지 않습니다. 마스킹은 도구가 출력하는 내용에만 적용되며 렌더링된 아티팩트에는 절대 미치지 않고, dist/는 렌더링이 생성한 그대로 출력됩니다. 키워드와, 이를 선언해서 얻을 수 있는 것의 전체 한계는 vocabulary/compact-form-authoring.md의 “Declaring a leaf sensitive”에 있습니다.
보류된 값 표시하기
--unredacted는 민감으로 선언된 값을 보류하지 않고 출력하며, 모든 inspect 화면(위의 읽기용 레이아웃과 Release의 컴파일 그래프 모두)에 한 번에 적용됩니다. 이 플래그가 존재하는 이유는 보류된 값이 때로는 바로 조사 대상이기 때문입니다. 잘못된 연결에서 온 자격 증명은 둘 다 보류된 것으로 표시되면 올바른 것과 똑같아 보입니다.
이 플래그는 전달된 명령에만 적용됩니다. aggrega build와 aggrega validate도 이 플래그를 받으며, 이때는 --ir-graph가 반환하는 그래프에만 적용되고, 그래프를 요청하지 않으면 플래그를 거부합니다. aggrega build --trace-unredacted는 같은 개념을 빌드의 트레이스 파일에 적용한 것이며, 빌드의 두 플래그 중 어느 것도 다른 플래그의 출력에는 미치지 않습니다. dist/ 아래의 렌더링된 아티팩트는 이들 모두의 영향을 받지 않는데, 무엇을 전달하든 렌더링이 생성한 그대로 출력되기 때문입니다.
그러면 출력이 도달하는 모든 곳(터미널, 파이프, 파일, 화면 녹화, 붙여 넣은 버그 보고서)에 해당 값이 평문으로 담깁니다. 각각 마스킹 없이 캡처되었다는 헤더로 시작하는 트레이스 파일과 달리, 터미널 출력에는 그러한 표시가 없습니다. 플래그가 전달되었다는 사실은 명령줄만이 알려 줍니다.
inspect를 사용할 때
- “이 Feature가 왜 여기 있는가?” 디버깅 — 어노테이션 기반 연결은 Aggregate 및 Release YAML 파일에서 보이지 않습니다(어노테이션은 있지만, 어노테이션이 합성하는 Feature 연결은 IR에만 존재합니다). Inspect는 이를 출처와 함께 드러냅니다.
- 스키마 상속 확인 —
aggrega inspect <ComponentName>는extends:체인이 해석된 후의 병합된 스키마를 보여 줍니다. 작성된 파일만으로는 로컬 차이만 보입니다. - 측 간 합성의 예상치 못한 결과 진단 — Aggregate 어노테이션과 Release 어노테이션이 모두 같은 Feature에 필러 페이로드를 제공하면, 해석된 리프를 머릿속으로 재구성하기 어려울 수 있습니다. 리프별 대괄호 형식은 해석 과정을 명시적으로 보여 줍니다.
- 배포 전 확인 점검 —
aggrega inspect ./prod-release.yaml는aggrega build가 아티팩트를 생성하기 전에 모든 Component의 모든 Feature를 나열합니다. 운영자는 렌더링된 매니페스트를 GitOps에 커밋하기 전에 토폴로지가 의도와 일치하는지 확인할 수 있습니다.
기반 메커니즘 — 어노테이션이 계단식으로 적용되는 방식, 측-대-필러 분할이 어노테이션 값을 Feature 필러로 라우팅하는 방식, 명시적 연결 우선 원칙이 어노테이션 기반 기여와 상호 작용하는 방식 — 은 providers/well-known-annotations.md 및 entities/manifest.md “Annotation-Driven Feature Bindings”를 참조하십시오.
개요
aggrega inspect [identifier] [flags]설명
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--catalog | [] | 카탈로그 디렉터리이며 반복할 수 있습니다. 각 —catalog <dir>는 카탈로그 검색 스택의 앞에 추가됩니다(처음 일치하는 항목이 우선). 스택은 워크스페이스 catalog_dirs이거나, 워크스페이스 구성이 workspace.releases 아래에서 자체 디렉터리를 지정한 Release의 경우 해당 Release의 디렉터리이며, 워크스페이스 루트에 catalog라는 이름의 디렉터리가 있으면 그것으로 끝납니다. 비어 있게 작성된 catalog_dirs 목록은 로컬 카탈로그를 전혀 읽지 않습니다. |
--closure | false | 해석된 노드 보기 대신 Release의 의존성 클로저 — 도달하는 모든 카탈로그 엔터티와 각각이 해석된 버전 — 를 보고합니다. 클로저를 해석하는 유일한 종류인 Release에 적용되며, 다른 종류는 요청을 조용히 무시하지 않고 거부합니다. |
--color | auto | 출력 색상 지정: auto|always|never. |
--detail | false | 필드 본문 전체를 렌더링합니다. |
--flat | false | 트리 형태 엔터티(Aggregate, Release)를 평면 목록으로 렌더링하며, 각 노드 앞에 전체 점 표기 경로를 붙입니다. 표 형태 종류에는 영향이 없습니다. |
--ir-graph | false | 이 명령이 이미 생성하는 모든 것에 더해, 이번 실행에서 계산한 IR 그래프를 JSON으로 stdout에도 씁니다. 작성자가 민감하다고 선언한 값은 보류되며, 대신 출력하려면 —unredacted를 전달합니다. 그래프로 해석되는 유일한 종류인 Release에 적용되며, 다른 종류는 요청을 조용히 무시하지 않고 거부합니다 |
--list | false | 식별자만 렌더링합니다. |
--no-color | false | 색상 출력을 비활성화합니다(—color=never의 별칭). |
--output, -o | text | 출력 형식: text|yaml. |
--plugin | — | 원시 <file.wasm> 아티팩트의 파일 시스템 경로입니다. aggrega plugin sync가 Plugin 엔터티에 기록하기 전에, 해당 아티팩트가 가져오는 호스트 함수를 도출하여 출력합니다. 식별자 인수를 받지 않습니다. |
--raw | false | 엔터티를 해석 없이 작성된 그대로 렌더링합니다. |
--release | — | 이 Release 파일의 조건으로 카탈로그 이름을 조회합니다. 워크스페이스 구성이 해당 Release에 지정한 카탈로그 디렉터리를 사용하며, —catalog가 앞에 추가됩니다. 이름에 적용되며, 파일이나 레지스트리 참조는 있는 그대로 검사되고 이 플래그를 거부합니다. 상대 경로는 워크스페이스 루트가 아니라 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 해당 디렉터리가 어떤 워크스페이스에도 속하지 않고 루트도 지정되지 않은 경우, 절대 경로는 Release 자체 폴더에서 워크스페이스를 찾습니다 |
--resolved | false | 엔터티를 완전히 해석하여 렌더링합니다. |
--show-implements | false | Recipe 또는 FeatureRecipe의 경우 spec.implements를 카탈로그에 대해 해석하고 바인딩된 Component 또는 Feature를 렌더링합니다. |
--unredacted | false | 작성자가 민감하다고 선언한 값을 보류하지 않고 출력합니다. 그러면 출력이 도달하는 모든 곳 — 터미널, 파이프, 파일, 화면 녹화 — 에 해당 값이 평문으로 남습니다. |