aggrega registry
레지스트리와 그 서명 신뢰 정책 관리
개요
aggrega registry설명
Manage the OCI registries Aggrega publishes to and resolves from, together withthe signature trust policy for each.
A registry entry records where to reach the registry and what to require of thesignatures on artifacts it serves — which identities are trusted, and whether asignature is required at all. That policy is what "aggrega pull" enforces whenit verifies an artifact and what "aggrega push" honours when it decides whetherto sign.
"aggrega registry add" can fetch a registry's own advertised trust policy ratherthan having you write it out. "aggrega registry update" builds the localsearchable index that "aggrega search" and "aggrega plugin add" read.
A registry entry is written to the global config shared across every workspaceon this machine, because a registry and the identities you trust on it areusually the same wherever you work. That makes adding or removing one amachine-wide change: every project on this machine resolves through the entryyou just wrote or dropped. Pass --workspace to write it to this project's configfile instead. Building the searchable index is the exception — that lands inthis workspace's own artifact cache and reaches no other project.하위 명령
| 명령 | 설명 |
|---|---|
aggrega registry add | 레지스트리와 그 서명 신뢰 정책을 등록합니다 |
aggrega registry list | 구성된 레지스트리와 그 신뢰 상태를 나열합니다 |
aggrega registry remove | config 파일에서 레지스트리와 그 신뢰 정책을 제거합니다 |
aggrega registry update | 구성된 레지스트리의 검색 가능한 로컬 인덱스를 빌드합니다 |
aggrega registry add 설명
Register a registry host and its signature trust policy.
The entry is keyed under the host exactly as written, and every lookup of it ismade in one spelling: a lowercase host name containing a dot, localhost, a singlename followed by a port (registry:5000), an IPv4 address, or an IPv6 address inbrackets, each with an optional :port. A reference may be given instead — itsscheme, path and credentials are dropped and the entry is keyed under the host itnames — but a host written in capitals, with the default HTTPS port, or as asingle name with no port is refused, naming the spelling to write where there isone.
The entry is written to the global config shared across every workspace, since aregistry and the identities you trust on it are usually the same wherever youwork. Pass --workspace to write it to this project's config file instead; the twoflags are mutually exclusive.
By default the registry's advertised trust policy is fetched once from theregistry's own origin (https://<host>/.well-known/aggrega-trust) and pinnedlocally — trust-on-first-use. Verification at pull time always runs against thepinned local policy, never a live re-fetch. Pass --fetch-trust=false to skip thefetch and pin only what the flags supply.
A trust policy can also be set by hand: keyless (one or more --identity entries,each an "identity=issuer" pair) or keyed (--key pointing at a pinned public-keyPEM). Manual --identity / --key flags OVERRIDE the fetched set — when either issupplied, the fetch is skipped and the policy is built from the flags alone.Pass --trusted-root to pin a Sigstore trust-root bundle for air-gapped keylessverification. Adding the official hub host with no policy flags pins the built-inofficial baseline.
When the registry advertises no trust policy (a 404 or an unreachable endpoint),the add does not fail: it writes the policy from the flags (or an empty policy)and prints a notice suggesting manual --identity / --key pinning. The officialhub writes its built-in baseline instead, and the notice says the baseline waspinned.
When the workspace is offline the advertised policy cannot be fetched, so theregistry is never asked. Adding a registry other than the official hub is thenrefused unless --identity or --key supplies the policy, rather than writing anentry that trusts nothing: register it once while online, or pin it by hand.Adding the official hub offline pins its built-in baseline, with a notice sayingso, and a manual policy registers offline exactly as it does online.
Existing settings in the target config file are preserved.aggrega registry add 플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--advisory | false | 이 레지스트리의 검증 실패를 중단하는 대신 경고로 낮춥니다 |
--fetch-trust | true | 처음 사용할 때 레지스트리가 알리는 신뢰 정책을 가져와 고정합니다. 건너뛰려면 —fetch-trust=false를 사용합니다. 수동으로 —identity/—key를 지정해도 가져오기를 건너뜁니다. |
--global | false | 모든 워크스페이스에서 공유하는 전역 config에 항목을 씁니다. 레지스트리는 기본적으로 여기에 기록됩니다. |
--identity | [] | identity=issuer 형식의 신뢰할 수 있는 키리스 ID입니다. 예: dev@example.com=https://accounts.google.com (반복 가능, OR 집합). 가져온 신뢰 정책을 재정의합니다. |
--key | — | 키 기반 검증에 사용할, 고정된 cosign 호환 공개 키 PEM의 경로입니다. 가져온 신뢰 정책을 재정의합니다. |
--name | — | 이 레지스트리의 선택적 별칭입니다. 호스트가 계속 식별자 역할을 하며, 별칭은 레지스트리를 지정하는 모든 곳(예: —registry)에서 호스트로 해석됩니다. 레지스트리 간에 고유해야 합니다. |
--require-signatures | false | 이 레지스트리에서 가져오는(그리고 푸시하는) 모든 아티팩트에 서명을 요구합니다 |
--trusted-root | — | 에어갭 환경의 키리스 검증에 사용할, 고정된 Sigstore 신뢰 루트 번들의 경로입니다 |
--workspace | false | 전역 config 대신 이 프로젝트의 워크스페이스 config에 항목을 씁니다. |
aggrega registry list 설명
List every registry configured in the effective merged config, one per line,with its friendly alias (if any), a short trust-posture summary, and a marker onthe default registry.
This reads the resolved configuration and never contacts a registry. Registriesare listed in ascending host order.
With -o json the same set is emitted as one structured document per registry:its host, its alias, whether it is the default, its trust posture as discretefields rather than the table's rendered sentence, and whether a credential forthat host is present in the shared credential store. The credential state reportspresence only — a credential is never read out, measured, or shown in any form,and whether the registry would accept it is not asked, since that would take anetwork round trip. Reading it consults the local credential store, which honorsa configured credential helper. The order is the same ascending host order thetable uses.aggrega registry list 플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--output, -o | table | 출력 형식: table|json. |
aggrega registry remove 설명
Remove a registry's trust-policy entry from a config file, addressed by its hostor its friendly alias.
By default the entry is removed from the global config shared across everyworkspace; pass --workspace to remove it from this project's workspace configinstead. Setting both --global and --workspace is a usage error.
The default_registry pointer is left untouched — removing a registry's trustpolicy reverts that host to default trust; it does not change which registry isthe default. Where default_registry names the removed entry by its alias, thatalias names nothing afterwards, and the configuration is refused untildefault_registry is written as a host or as another entry's name.aggrega registry remove 플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--global | false | 모든 워크스페이스에서 공유하는 전역 config에서 항목을 제거합니다. |
--workspace | false | 전역 config 대신 이 프로젝트의 워크스페이스 config에서 항목을 제거합니다. |
aggrega registry update 설명
Walk each configured registry's repositories, read the latest published versionof each, and write a deterministic local searchable index to the artifact cache.
With no argument, every configured registry is indexed. With a single registryargument (a host or a friendly alias), only that registry is indexed.
This is the one registry command that reaches the network. The index it writeslands in this workspace's own artifact cache, so refreshing it changes nothinganother project on this machine resolves through. Credentials are read from asupplied or ambient source and never asked for: a registry that needs one you donot have fails with a message naming what it wanted.
For each repository the highest strict-SemVer version is selected (pre-releaseversions are skipped) and its catalog facets — kind, description, category,labels, and, for plugins, socket type and capabilities — are recorded from thepublished manifest. A repository with no conforming version is skipped; arepository that cannot be read is skipped with a note, so one unreadablerepository does not abandon the whole index.
A registry that asks the walk to slow down — a 429 answer, or a 503 that sayshow long to wait (Retry-After) — is left alone for as long as it asks, or tenseconds where it does not say, and the walk reads fewer of its repositories atonce until it answers again, then returns to its usual pace; on a terminal thewait is shown beside that registry's row. A registry that answers nothing but"slow down" for five minutes is not indexed: it keeps the index it had beforethe run, and the command names it, its last answer and how long it waited.
A read the registry fails or drops in passing — a 5xx answer, a connectionreset or timed out, an answer cut short — is asked again a few times, with agrowing wait between attempts. A repository with a read stillfailing after that is not recorded from this run: it keeps the record the indexalready holds for it, where that record was judged under the trust policy now inforce, and is otherwise left out of the index; either way it is named as arepository that could not be read, as the walk goes and again in the closingsummary under its registry's row, with the kind of the read's last failure — thestatus the registry answered, a timeout, a reset, an answer cut short — and theread that failed. So a version is never recorded unsigned,undated or without its deprecation marker because a read failed, with or without--upgrade. Each registry's row in the closing summary also says how many readswere asked again, whether or not they then succeeded — a read sent again afterthe registry asked the walk to slow down among them — and says zero when nonewas.
Every signature a registry's walk verifies against the public Sigstore trust rootis verified against the same copy of that root, fetched once for the walk ratherthan once per signature; a registry whose trust policy pins a trust root of itsown is verified against that file.
A registry whose repository listing repeats itself — naming a repository it hasalready named, or answering two pages in a row with no repository while stillpointing to a next page — is not followed round again. That registry is reportedas not indexed, with a message naming it and saying its repository listingrepeated itself; the other registries are still indexed, and the command exitsnon-zero.
A registry that is not indexed keeps the index it had before the run, unchanged:nothing is written for a registry whose walk failed, whose listing repeateditself, or that was being walked when the command was interrupted. Registriesindexed earlier in the same run keep what this run wrote for them. A registry'snew index is written aside and put in place whole, so a command stopped whilewriting one leaves that registry with a complete index — the one it had beforethe run, or the new one — or with none, never with a partial one.
Every strict-SemVer version a recorded repository publishes is listed too, eachwith the manifest digest its tag resolves to — the address of the exact bytespublished under that version. Where the registry's trust policy pins a public keyor trusted identities, and verification is not switched off, each version's ownsignatures are verified against that policy and the signer is recorded when oneverifies; a version with no signature, or none that verifies, is recorded with nosigner. Where several verify, the signer recorded is the one the transparency logrecorded earliest, whatever order the registry lists them in, so signing a versionagain never changes its recorded signer.
Each version's publication date is recorded too, with its source. Where one of theversion's keyless signatures verified, the date is the time the transparency logrecorded that earliest signature, as the verified log entry attests it (source'transparency-log') — so signing a version again never moves its date. Otherwiseit is the date the publication itself stated beside what it published (source'publisher'), the earliest where several are stated: the publishing machine's ownclock, which nothing attests, read from any registry whatever its trust policy.A version with neither — published without stating a date, and not signedkeyless in a way this policy verifies — is recorded with no date.
Only manifests, signature attachments and publication-date attachments are read:no entity's content is fetched. 'aggrega search -o json' reports these under eachrecord's 'published' field.
The per-repository records are byte-identical across two runs against the sameregistry state; the freshness timestamp is written to a sibling file so it neverdisturbs the records.
A refresh reads again only what changed, and finds every change a full re-readwould. For each repository it revalidates the tag listing with a conditionalrequest, resolves every version's tag to its manifest digest, and revalidates everyversion's attachments — its signatures, publication-date statements and deprecationmarkers — with one conditional request, plus one for the signatures of adeprecation marker it judged before. A version whose digest or attachments changedis read again in full, and its signatures and markers are verified again exactly asa full re-read verifies them; everything else is kept as recorded. A change to thisregistry's trust policy reads every version again under the policy now in force, andso does a repository whose entry in the index records none of these checks. Anunchanged registry therefore costs one conditional request per repository and twosmall requests per version (three where a deprecation marker was judged), withnothing downloaded. A version is read again on the next refresh where it carries adeprecation marker that was not honored, or where this run got no way torevalidate its attachments — which, on a registry that offers none, is everyversion.
Several repositories are read at a time. Everything the command records and printscomes out in repository order, so the index and the output are the same as readingone repository at a time would produce.
While it walks, a terminal shows the walk's progress on standard error, the waybuild and pull show theirs: a row naming each registry, a spinner while thatregistry's repository listing is read, then how many of its repositories the walkhas finished out of how many it lists, counted in repository order, and a bar forthe whole walk below the rows. On a terminal that cannot redraw in place, or with--plain, each registry gets one plain line instead, written when its walk ends,with the count it ended on and the time it took. When standard error is not aterminal, no progress is shown. The progress changes nothing the command prints onstandard output.
Use --upgrade to read every repository in full, comparing nothing with the indexalready written — to rebuild an index from the registry alone. It finds no change arefresh without it would miss.
Each published version's deprecation markers are read as the walk goes, and the oneswhose own signature verifies are recorded into the index. Every marker read isreported, whether or not it was recorded — a version kept as recorded is not read, soits marker is not reported again — and each registry reports how many markers itsindex now records, including when that number is zero. Where signatureverification is disabled for a registry, the walk reports that its markers were notexamined rather than a count, so a registry that published nothing is never confusedwith one this run had no basis to judge.aggrega registry update 플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--upgrade | false | 모든 저장소를 전부 읽으며, 이미 작성된 인덱스와 아무것도 비교하지 않습니다(이 플래그가 없는 새로 고침도 바뀐 것은 이미 모두 다시 읽습니다) |
registry update가 사용 중단 마커에 대해 보고하는 내용
aggrega registry update는 레지스트리를 순회하면서 게시된 각 버전의
사용 중단 마커를 읽고, 인증할 수 있는 마커를 로컬 인덱스에 기록합니다.
이 검사 결과는 모든 경로에서 보고되므로, 마커를 하나도 게시하지 않은 레지스트리와
마커를 찾지 않은 실행을 구별할 수 있습니다.
순회가 읽는 각 마커는 저장소, 버전, 게시자가 기록한 심각도(warning, error 또는 retracted)와 함께 마커가 기록되었는지 여부를 나타내는 한 줄을 출력합니다. 마지막 새로 고침 이후 첨부 항목이 바뀌지 않은 버전은 읽지 않고 기록된 그대로 유지되므로 그 마커는 다시 보고되지 않지만, 아래의 개수에는 여전히 포함됩니다. 마커는 자체 서명이 레지스트리의 신뢰 정책이 인정하는 서명자에 대해 검증될 때에만 기록됩니다. 존재하지만 디코딩되지 않거나, 존재하지만 인정되지 않는 마커는 그렇게 보고되며, 인증할 수 없는 근거로 기록되는 대신 인덱스에서 제외됩니다. 레지스트리가 보유하지 않는다고 응답하는 마커도 마찬가지입니다. 읽기에 실패한 마커는 다른 경우입니다. 실패한 읽기를 참조하십시오.
이어서 각 레지스트리는 현재 인덱스에 기록된 마커의 수를 보고하며, 그 수가 0인 경우에도 보고합니다. 서명 검증이 전역적으로 또는 해당 레지스트리에 대해서만 꺼져 있는 경우에는, 순회가 대신 그 레지스트리의 마커를 검사하지 않았다고 보고합니다. 두 가지는 서로 다른 사실입니다. 앞의 것은 레지스트리가 이 워크스페이스가 활용할 수 있는 것을 하나도 게시하지 않았다는 뜻이고, 뒤의 것은 이번 실행에 마커를 판단할 신뢰 근거가 전혀 없었다는 뜻입니다. 마커를 검사하지 않은 레지스트리는 버전 선택에서 어떤 철회도 반영하지 않으므로, 마커를 첨부한 작성자가 그 줄을 보면 마커가 효과가 없는 이유를 알 수 있습니다.
각 버전이 기록하는 게시 날짜
게시된 매니페스트의 생성 시각은 고정되어 있으므로, 그 다이제스트는 무엇이 게시되었는지에만 의존하며 언제 게시되었는지에는 결코 의존하지 않습니다. 따라서 버전이 게시된 날짜는 매니페스트 옆에서 읽으며, aggrega registry update는 각 버전에 대해 이 날짜를 그 출처와 함께
기록합니다:
transparency-log— 버전의 서명이 키리스(keyless)이고 레지스트리의 신뢰 정책에 대해 검증되는 경우, 투명성 로그가 그 서명을 기록한 시각이며, 이는 로그의 서명된 약속이 증명합니다. 버전의 서명 여러 개가 검증되는 경우에는 그 시각 중 가장 이른 것이며, 해당 버전에 기록되는 서명자도 바로 그 서명의 서명자입니다 — 레지스트리가 서명을 어떤 순서로 나열하든 마찬가지이므로, 다시 서명된 버전도 날짜와 서명자를 유지합니다. 게시와 동시에 서명된 버전이라면 이는 게시 시점이고, 게시 후aggrega sign으로 처음 서명된 버전이라면 서명된 시점입니다. 이 출처가 존재하면 항상 이 출처가 우선합니다.publisher— 그렇지 않은 경우, 게시물이 게시한 대상 옆에 명시한 시각입니다. 이는aggrega push와aggrega push-artifact가 작성하는 작은 published-at 첨부물로, 게시하는 머신 자체의 시계 값을 담고 있으며 아무것도 이를 증명하지 않습니다. 이는 신뢰 결정이 아니라 게시자의 진술이므로, 신뢰 정책과 관계없이 모든 레지스트리에서 읽습니다. 여러 개가 첨부된 경우 가장 이른 것을 사용합니다.
둘 다 없는 버전은 날짜를 기록하지 않습니다. 이는 날짜를 명시하지 않은 게시물로서, 그 서명이
이 정책이 검증하는 키리스 서명이 아닌 경우입니다 — 예를 들어 어떤 키리스 ID도 신뢰하지 않는 정책에서 읽은 키리스 게시물이 그렇습니다. 키리스 게시물은 자체적으로 날짜를 명시하지 않기 때문입니다. aggrega search -o json은 각 버전 아래 published에 날짜를 보고합니다.
새로 고침이 다시 읽는 항목
새로 고침은 레지스트리가 지금 제공하는 내용을 인덱스가 기록한 내용과 비교하고, 바뀐 것을 모두 다시 읽습니다. 그 결과는 전체를 다시 읽었을 때와 같습니다. 각 저장소에 대해 새로 고침은 다음을 수행합니다:
- 태그 목록을 재검증하여, 그 이후 게시되거나 삭제된 버전을 반영합니다.
- 각 버전의 태그를 그 태그가 가리키는 매니페스트로 해석하여, 기존 태그로 다시 게시된 이전 버전을 다시 읽습니다.
- 각 버전의 첨부 항목(서명, 게시일 명시, 지원 중단 마커)을 재검증하여 그 이후 버전에 첨부된 서명, 날짜 또는 마커를 읽고 검증하며, 이전에 판단한 지원 중단 마커의 서명에 대해서도 같은 작업을 수행합니다.
- 레지스트리의 신뢰 정책을 인덱스가 구축될 때의 정책과 비교하여, 정책이 바뀌면 모든 버전을 새 정책에 따라 다시 읽습니다.
지원 중단 마커, 서명, 게시일은 각각 게시된 버전을 가리키는 별도의 객체로 그 버전에 첨부되며, 바로 이 방식 덕분에 게시자는 버전을 다시 게시하지 않고도 지원 중단하거나 서명할 수 있습니다. 따라서 이들 중 어느 것도 태그를 추가하거나 버전 자체의 매니페스트를 바꾸지 않습니다. 이들이 바꾸는 것은 버전의 첨부 항목이며, 세 번째 검사가 재검증하는 것이 바로 이것입니다. 버전 제외와 aggrega inspect는 모두 이 인덱스를 읽으므로, 마지막 새로 고침 이후 철회된 버전은 다음 새로 고침이 실행되면 선택에서 제외되고 표시됩니다.
각 검사는 작은 요청입니다. 매니페스트 다이제스트 해석이거나, 레지스트리가 아무것도 보내지 않고 변경 없음으로 응답하는 조건부 요청입니다. 따라서 변경되지 않은 레지스트리를 새로 고칠 때는 아무것도 내려받지 않습니다. 인정되지 않은 지원 중단 마커를 지닌 버전이나, 이번 실행에서 첨부 항목을 재검증할 방법이 없었던 버전은 다음 새로 고침에서 다시 읽습니다. 버전의 첨부 항목이 바뀌었는지 알려 줄 수 없는 레지스트리는 새로 고침할 때마다 모든 버전을 다시 읽습니다. 결과는 같으며, 비용도 전체를 다시 읽는 것과 같습니다.
--upgrade는 이미 작성된 인덱스와 아무것도 비교하지 않고 모든 저장소를 전부 읽습니다. 레지스트리만으로 인덱스를 다시 구축할 때 사용합니다. 새로 고침이 놓치는 것을 이 플래그가 추가로 찾아내지는 않습니다.
속도를 늦추라고 요청하는 레지스트리
공식 허브인 hub.aggrega.ai는 짧은 시간 동안 한 주소에서 올 수 있는 요청 수를 제한하므로, 주소를 공유하는 머신들은 그 허용량을 함께 나눠 쓰며, 어떤 레지스트리든 같은 방식으로 클라이언트를 제한할 수 있습니다. 한도를 넘은 레지스트리는 429 Too Many Requests로 응답하거나, 얼마나 기다려야 하는지 알려 주는 Retry-After 헤더와 함께 503 Service Unavailable로 응답합니다. 명령줄이 레지스트리에 보내는 모든 요청은 명령에 관계없이 이 응답에 같은 방식으로 대응합니다. 레지스트리가 요청한 만큼, 또는 응답에 명시되지 않은 경우 10초 동안 기다리고, 여기에 무작위로 최대 1초를 더 기다린 뒤 다시 요청하며, 정해진 시도 횟수는 없습니다. 거부된 요청뿐 아니라 해당 레지스트리에 대한 모든 요청이 함께 기다리며, 동시에 보내는 요청 수도 줄어듭니다. 레지스트리가 요청할 때마다 절반으로 줄어 최소 하나까지 내려가고, 실패 없이 처리된 일련의 요청마다 하나씩 다시 늘어나 명령의 평소 수로 돌아갑니다. 대기는 명령의 나머지 진행 상황과 같은 조건으로 hub.aggrega.ai asked to slow down; waiting 11 s 같은 줄로 표시됩니다. aggrega build, aggrega pull, aggrega registry update는 진행 중인 단계 옆에 표시하고, 기다리는 대상을 표시하는 다른 명령은 별도의 단계로 표시합니다. 단, 여러 참조를 동시에 서명하는 aggrega sign --jobs는 그 대기들을 하나의 단계로 표시합니다. 표준 오류가 터미널이 아닌 경우에는 명령의 --progress가 요청하지 않는 한 아무것도 표시되지 않습니다. 5분 동안 “속도를 늦추라”는 응답만 하는 레지스트리는 E0378로 거부되며, 해당 레지스트리, 마지막 응답, 그리고 다른 응답 없이 지난 시간이 표시됩니다. 5분은 고정되어 있으며 이를 변경하는 설정은 없습니다. 그러면 aggrega registry update는 마지막 요약의 Not indexed: 아래에 해당 레지스트리를 표시하며, 그 레지스트리는 실행 전에 가지고 있던 인덱스를 유지합니다.
실패한 읽기
순회는 레지스트리에서 작은 객체를 많이 읽으며, 일부 읽기는 일시적으로 실패합니다. 레지스트리가 실패했거나 사용할 수 없다고 응답하거나(대기 시간을 알려 주는 503을 제외한 5xx 상태), 요청이 시간 초과되었다고 응답하거나(408), 연결이 재설정되거나 시간 초과되거나, 응답이 완료되기 전에 중단되는 경우입니다. 이러한 각 읽기는 시도 사이의 대기 시간을 점점 늘려 가며 몇 번 다시 요청됩니다. 순회에 속도를 늦추라고 요청하는 레지스트리는 읽기를 실패시키는 것이 아닙니다. 읽기는 속도를 늦추라고 요청하는 레지스트리에서 설명하는 대로 기다린 뒤 다시 요청되며, 5분 동안 계속 요청하는 레지스트리는 한 저장소의 순회가 아니라 그 레지스트리의 순회를 끝냅니다.
그래도 실패한 읽기는 결코 응답으로 간주되지 않습니다. 읽을 수 없었던 서명은 서명이 없는 버전을 뜻하지 않으며, 읽을 수 없었던 지원 중단 마커는 한 번도 철회되지 않은 버전을 뜻하지 않으므로, 순회는 이번 실행에서 그 저장소에 대해 아무것도 기록하지 않습니다. 인덱스가 그 저장소에 대해 이미 보유한 기록이 현재 적용 중인 레지스트리 신뢰 정책 아래에서 판정된 것이라면 저장소는 그 기록을 유지하고, 그렇지 않으면 인덱스에서 제외됩니다. 어느 경우든 순회는 진행 중 출력에서 그 저장소를 명시하며 둘 중 어느 쪽이 일어났는지와 어떤 읽기가 실패했는지를 알리고, 마지막 요약에서도 레지스트리 행 아래 별도의 줄에, 읽을 수 없었던 저장소들 가운데 다시 명시합니다:
Indexed 1 registry. registry.example.com: 41 entities, 1 repository could not be read, 4 reads retried component/core/web: the registry answered 503 Service Unavailable: …레지스트리 행은 다시 요청된 읽기의 수도 알려 주며, 각 읽기는 몇 번 시도했는지, 그 후 성공했는지와 관계없이 한 번으로 계산되고, 다시 요청된 읽기가 없으면 0 reads retried라고 표시합니다. 결국 모든 읽기가 성공한 순회는 그 행에 저장소를 표시하지 않으므로, 저장소 하나를 빠뜨리기에 얼마나 가까웠는지를 알려 주는 것이 이 개수입니다.
이러한 각 줄은 해당 읽기의 마지막 실패 종류, 즉 레지스트리가 응답한 상태, 시간 초과된 읽기, 재설정된 연결, 중간에 끊긴 응답으로 시작하고, 그 뒤에 어떤 읽기였는지를 알려 주는 실패 자체가 이어집니다. 이 중 어느 종류에도 해당하지 않는 실패, 예를 들어 서명을 검증할 신뢰 루트를 얻을 수 없었던 경우는 실패만 표시됩니다. aggrega serve의 aggrega/registryUpdate 메서드는 각 호스트의 skipped 아래에 같은 저장소를 각각 같은 reason과 함께 응답하며, 다시 요청된 읽기의 수를 readsRetried로 응답합니다. 새로 고침과 --upgrade에도 똑같이 적용되며, 다음 순회는 어느 저장소에서나 그렇듯 그때 인덱스가 보유한 내용에서 시작합니다.
키 기반 정책이 고정하는 공개 키
키 기반 신뢰 정책은 레지스트리의 공개 키를 항목의 public_key로 인라인에 고정합니다.
aggrega registry add --key <file>은 파일의 내용을 그곳에 복사하며, 레지스트리가 알리는 정책 중 키가 들어 있는 정책을
고정할 때도 마찬가지입니다. 값은 PEM 공개 키 블록입니다. 즉 -----BEGIN PUBLIC KEY----- 줄 또는 -----BEGIN RSA PUBLIC KEY----- 줄부터
이에 대응하는 -----END 줄까지의 텍스트이며, 블록 위에 있는 텍스트는 무시됩니다.
-----BEGIN … PUBLIC KEY----- 줄이 없는 값은 구성 파일을 불러올 때 거부되며,
이때 파일과 항목의 이름이 표시됩니다. registry add도 쓰기 전에 같은 검사를 수행하므로,
그 밖의 내용을 담은 --key 파일(개인 키, 인증서, 다른 인코딩의 키)은 거부되고 구성 파일은 그대로 유지됩니다. 검사하는 것은
이 줄뿐입니다. 블록이 사용 가능한 키로 디코딩되는지는 레지스트리의 서명을 이 키로 검증할 때
드러납니다.
오프라인
aggrega registry update는 이 그룹에서 작업 전체가 레지스트리를 순회하는 것인 유일한 명령이며, 오프라인 상태(구성 파일의 최상위 offline 키, AGGREGA_OFFLINE 또는 --offline)에서는 아무것도 순회하기 전에 거부합니다. 거부 메시지는 세 가지 중 어느 것이 이 상태를 설정했는지 알려 줍니다.
대신 사용할 부분적인 형태는 없습니다. 인덱스는 각 레지스트리가 현재 제공하는 내용을 기록하며, 이는 레지스트리에 묻지 않고는 알 수 없기 때문입니다. 오프라인 작업 공간이 할 수 있는 일은 이미 가진 인덱스를 읽는 것입니다. aggrega search와 aggrega inspect의 지원 중단 알림은 모두 로컬 스냅숏을 읽으며 네트워크가 전혀 필요하지 않으므로, 오프라인 상태가 막는 것은 갱신뿐입니다. 오프라인 작업 공간에서 한 번의 실행 동안 갱신하려면 --offline=false를 전달합니다.
aggrega registry add는 --fetch-trust=false, --identity 또는 --key가 가져오지 말라고 지정하지 않는 한, 레지스트리가 알리는 신뢰 정책을 위해 네트워크에 한 번 접속합니다. 오프라인 상태에서는 이 가져오기가 연결을 시도하기 전에 거부되므로 레지스트리에는 전혀 요청이 가지 않습니다. 이때 공식 허브가 아닌 레지스트리를 추가하는 것은 거부됩니다. 레지스트리를 추가하는 시점이 그 신뢰가 고정되는 유일한 순간이며, 정책 없이 기록된 항목은 아무것도 신뢰하지 않는 반면 이후의 모든 pull은 레지스트리를 그 항목에 맞춰 검사하기 때문입니다. 거부 메시지에는 짧은 코드 E0310이 붙으며 두 가지 해결 방법을 모두 알려 줍니다. 온라인 상태에서 한 번 등록하거나(--offline=false로 한 번의 실행에 한해 가능합니다), --identity 또는 --key로 정책을 직접 고정하는 것입니다. 후자는 제공한 내용을 그대로 등록하며 가져오기를 전혀 하지 않습니다. 공식 허브는 내장된 기준 정책으로 추가되며, 작업 공간이 오프라인이라 허브에 신뢰 정책을 요청하지 않고 대신 기준 정책을 사용했다는 알림이 표시됩니다. --fetch-trust=false는 온라인일 때와 똑같이 플래그에서 항목을 등록합니다. aggrega serve나 aggrega mcp를 통한 같은 등록도 똑같이 동작합니다. 같은 문구의 같은 거부가 발생하고, 그렇지 않으면 같은 항목이 기록됩니다. A registry is added offline with no trust policy to pin (고정할 신뢰 정책 없이 오프라인으로 레지스트리가 추가됨)에서 거부 메시지를 인용합니다.
list와 remove는 로컬 구성을 변경하거나 읽으므로 영향을 받지 않습니다.