aggrega search
구성된 레지스트리의 로컬 인덱스 검색
개요
aggrega search [query] [flags]설명
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach entity's name and description. The facet filters narrow the result further,combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe, workload, plugin); repeatable, case-insensitive --capability a plugin capability; repeatable --plugin-type a plugin socket type (for example provider, governance) -l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalogcategory is the label component.aggrega.ai/category, so'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere to look, so the command refuses: the reason goes to standard error,standard output carries nothing, and the exit status is non-zero. That is whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--capability | [] | 일치시킬 Plugin 기능입니다. 반복해서 지정할 수 있으며, 그중 하나라도 선언한 레코드는 유지됩니다. |
--include-retracted | false | 검증된 마커가 철회하더라도 게시된 가장 높은 버전을 보고합니다. 기본적으로 보고되는 버전은 해석(resolution)이 선택할 버전입니다. |
--kind | [] | 일치시킬 엔터티 종류입니다(component|feature|recipe|featurerecipe|workload|plugin). 반복해서 지정할 수 있으며, 그중 하나라도 일치하는 레코드가 유지됩니다. 대소문자를 구분하지 않습니다. |
--limit | 0 | 결과 수를 제한합니다(0은 제한 없음을 의미합니다). |
--output, -o | table | 출력 형식: table|json|names. |
--plugin-type | — | 일치시킬 Plugin 소켓 유형입니다(예: provider, governance, linter). |
--registry | — | 호스트 또는 별칭으로 지정한 이 레지스트리만 검색합니다. 기본값은 구성된 모든 레지스트리를 검색하는 것입니다. |
--selector, -l | — | 엔터티의 카탈로그 레이블에 대한 레이블 셀렉터이며, 카탈로그 레이블에는 카테고리가 포함됩니다(-l component.aggrega.ai/category=compute). |
레지스트리가 구성되지 않은 경우
검색은 이 머신이 접근하도록 구성된 레지스트리의 로컬 인덱스를 읽으므로, 레지스트리가 하나 이상 있어야 합니다. 구성된 레지스트리가 없으면 찾아볼 곳이 없으므로 aggrega search
는 응답하지 않고 거부합니다. 이유를 표준 오류에 쓰고, 0이 아닌 상태로 종료하며,
표준 출력은 비워 둡니다. 이는 --output json을 포함한 모든 출력 형식에서 동일합니다.
이 거부가 서로 다른 두 응답을 구별합니다. 실행되었지만 아무것도 일치하지 않은 검색은
0으로 종료하고 표준 출력에 (no matches)를 보고합니다. 아예 실행될 수 없었던 검색은
0이 아닌 상태로 종료하고 표준 출력에 아무것도 보고하지 않습니다. 따라서 종료 상태로 분기하는 스크립트는
“이 엔터티는 게시되지 않았다”와 “이 머신에는 물어볼 레지스트리가 없다”를 구별할 수 있으며, 이는 표준 출력의 알림과 0 상태로는 표현할 수 없습니다.
aggrega config init을 실행하여 서명 신뢰 정책과 함께 레지스트리를 등록한 다음,
aggrega registry update를 실행하여 검색이 읽는 로컬 인덱스를 빌드합니다.
aggrega registry list와 aggrega registry update는 같은 상황에 다르게 응답하며,
이는 의도된 것입니다. 레지스트리가 없을 때 레지스트리를 나열하는 것은 빈 집합에 대한 완전한 목록이며,
순회할 대상이 없는 인덱스 빌드는 더 할 일이 없습니다. 둘 다 완료된 작업이므로
둘 다 표준 출력에 보고하고 0으로 종료합니다. 요청받은 작업을 수행할 수 없었다고 보고하는 것은 검색뿐입니다.
검색이 보고하는 버전
VERSION 열에는 해석이 선택할 버전이 들어갑니다. 게시자가 철회한 버전은
보고되지 않습니다. 단, 철회에 이 워크스페이스의 신뢰 정책이 검증하는 서명이 있어야 합니다. 이는 철회가 pull에 영향을 미치는지 결정하는 것과 같은 두 조건이므로,
검색과 pull은 어떤 버전이 답인지에 대해 일치합니다.
어느 한 조건이라도 충족하지 못하는 철회는 보고 내용을 전혀 바꾸지 않습니다. 권고(advisory) 심각도의 마커는 해당 버전을 선택 가능한 상태로 두며, 서명이 검증되지 않는 마커는 이 워크스페이스가 따르는 주장이 아닙니다. 두 경우 모두 게시된 가장 높은 버전이 마커가 전혀 없을 때와 똑같이 보고됩니다.
철회된 버전이 있는 엔터티도 여전히 나열됩니다. NOTES 열은 제외된 버전을 명시하며,
보고할 내용이 있는 결과에만 나타납니다. 게시된 모든
버전이 철회된 엔터티는 결과에서 제외되지 않고, 버전으로 (none)과 남은 버전이 없다는
메모와 함께 보고됩니다. 생략된 엔터티는 존재하지 않는 엔터티와 구별할 수 없기 때문입니다.
--include-retracted를 전달하면 철회 상태와 관계없이 게시된 가장 높은 버전을 보고하며,
이는 “무엇을 사용해야 하는가?”가 아니라 “무엇이 게시되었는가?”에 대한 답입니다. 이 플래그는
보고되는 버전만 바꿉니다. NOTES 열은 어느 경우든 철회된 버전을 명시합니다.
검색이 읽는 것은 aggrega registry update가 쓰는 로컬 인덱스이므로,
해당 인덱스가 마지막으로 빌드된 시점에 각 레지스트리가 명시한 내용을 보고합니다. 그 이후에 철회된 버전은
아직 기록되지 않으며, 표준 오류에 쓰이는 최신성 줄에 각
인덱스가 빌드된 시점이 표시됩니다.
기계 판독 가능한 결과
--output json은 같은 계약을 두 필드로 전달합니다.
version은 해석이 선택할 버전입니다. 게시된 모든 버전이 철회되면 빈 문자열이며, 이때 그 버전을 모두 명시하는retracted목록이 함께 제공됩니다.retracted는 해당 선택에서 제외된 버전을 버전 오름차순으로 나열합니다. 제외된 버전이 없으면 이 필드는 없습니다.
어떤 버전을 받게 될지 알고자 하는 소비자는 version을 읽습니다. 대신
deprecations 배열에서 이를 도출하려면 심각도 및 서명 조건을 다시 구현해야 하며,
이러한 조건의 두 번째 구현은 컴파일러가 적용하는 구현과 얼마든지 달라질 수 있습니다. retracted는 이러한 조건이 이미 만들어 낸 결과를 보고합니다.
각 레코드에는 published도 포함됩니다. 이는 인덱스가 기록한 모든 버전을 버전 오름차순으로 나열하며,
각 버전에는 인덱스가 빌드될 때 태그가 해석된 manifestDigest와,
이 워크스페이스의 신뢰 정책이 해당 버전 자체의 서명을 검증한 경우 그 signer가 포함됩니다. 검증되는 서명자가 여럿이면
투명성 로그가 가장 먼저 기록한 서명자입니다. signer가 없는 버전에는
그 정책이 검증한 서명이 없으며, 그 외에는 아무것도 언급되지 않습니다.
한 버전의 콘텐츠를 읽는 소비자는 그 다이제스트로 주소를 지정하므로(예:
aggrega inspect oci://<host>/<repository>@<digest>), 이후 태그가 어떻게 되든 읽는 것은 인덱스가
기록한 바이트입니다.
버전이 게시된 시점이 어딘가에 기록되어 있으면, 해당 항목에는 UTC 기준 초 단위의 RFC 3339 타임스탬프인 publishedAt과
그 출처를 나타내는 publishedAtSource도 포함됩니다.
transparency-log는 투명성 로그가 버전의 키리스 서명을 기록한 시각으로,
이 워크스페이스의 신뢰 정책이 그 시각에 대한 로그의 서명된 약속과 함께 검증한 것입니다. 이는 signer의 서명, 즉 검증되는 서명 중 가장 이른 것이므로 버전에 다시 서명해도
어느 것도 바뀌지 않습니다. publisher는 게시물이 게시한 내용과 함께 명시한 시각으로,
게시하는 머신 자체의 시계에서 나온 것이며 아무것도 이를 증명하지 않습니다. 두 값을 분리해 두므로 날짜로 정렬하는
소비자도 증명된 시각과 명시된 시각을 구별할 수 있습니다. 둘 다 없는 버전에는
날짜가 없으며, 그 외에는 아무것도 언급되지 않습니다. 각각이 언제 기록되는지는
aggrega registry update를
참조하십시오.