Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

aggrega search

Rechercher dans l’index local des registries configurés

Synopsis

aggrega search [query] [flags]

Description

Search the local index of the configured registries for entities matching a
free-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; search
reads it and contacts no network. Run 'aggrega registry update' first, and again
whenever you want to pick up newly published entities. A freshness line naming
each searched registry and when its index was last updated is written to standard
error, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched against
each 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 catalog
category 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 the
results are merged. With --registry (a host or a friendly alias), only that
registry's index is searched.
A search needs at least one configured registry. With none configured there is
nowhere 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 what
lets a caller tell a search that ran and matched nothing from a search that
could not be performed. Run 'aggrega config init' to register a registry with
its signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: a
version a publisher has retracted, where the retraction carries a signature
this workspace's trust policy verifies, is not reported. Such an entity is
still listed, and the versions left out are named in a NOTES column, so an
entity whose every published version is retracted is reported as existing with
no version to take rather than disappearing from the result. Pass
--include-retracted to report the highest published version whatever its
retraction status; the NOTES column names the retracted versions either way.
The same holds for 'aggrega search -o json', where the 'version' field carries
the version a resolution would take and a 'retracted' array names the versions
left out.

Options

OptionPar défautDescription
--capability[]Capacité de Plugin à rechercher. Répétable ; un enregistrement qui en déclare une quelconque est conservé.
--include-retractedfalseSignale la version publiée la plus élevée même lorsqu’un marqueur vérifié la retire. Par défaut, la version signalée est celle qu’une résolution retiendrait.
--kind[]Type d’entité à rechercher (component|feature|recipe|featurerecipe|workload|plugin). Répétable ; un enregistrement correspondant à l’un quelconque est conservé. Insensible à la casse.
--limit0Plafonne le nombre de résultats (0 signifie aucun plafond).
--output, -otableFormat de sortie : table|json|names.
--plugin-type—Type de socket de Plugin à rechercher (par exemple provider, governance, linter).
--registry—Recherche uniquement dans ce registre, désigné par son hôte ou son alias convivial. Par défaut, la recherche porte sur chaque registre configuré.
--selector, -l—Sélecteur de labels portant sur les labels de catalogue de l’entité, qui incluent sa catégorie (-l component.aggrega.ai/category=compute).

Lorsqu’aucun registre n’est configuré

Une recherche lit l’index local des registres que cette machine est configurée pour atteindre ; elle en nécessite donc au moins un. Si aucun n’est configuré, il n’y a nulle part où chercher, et aggrega search refuse plutôt que de répondre : la commande écrit la raison sur la sortie d’erreur standard, se termine avec un code non nul et laisse la sortie standard vide — dans chaque format de sortie, --output json compris.

C’est le refus qui permet de distinguer deux réponses différentes. Une recherche qui s’est exécutée et n’a rien trouvé se termine avec zéro et signale (no matches) sur la sortie standard ; une recherche qui n’a pas pu s’exécuter du tout se termine avec un code non nul et n’y signale rien. Un script qui se branche sur le code de sortie peut donc distinguer « cette entité n’est pas publiée » de « cette machine n’a aucun registre à interroger », ce qu’un avis sur la sortie standard accompagné d’un code nul ne peut pas exprimer.

Exécutez aggrega config init pour enregistrer un registre avec sa politique de confiance des signatures, puis aggrega registry update pour construire l’index local que lit la recherche.

aggrega registry list et aggrega registry update répondent différemment à la même situation, et c’est délibéré. Lister les registres lorsqu’il n’y en a aucun est une liste complète d’un ensemble vide, et une construction d’index sans rien à parcourir n’a plus rien à faire : ce sont deux opérations terminées, donc toutes deux répondent sur la sortie standard et se terminent avec zéro. Seule la recherche signale qu’elle n’a pas pu faire ce qui lui était demandé.

La version signalée par une recherche

La colonne VERSION contient la version qu’une résolution retiendrait. Une version que son éditeur a retirée n’est pas signalée, à condition que le retrait porte une signature que la politique de confiance de cet espace de travail vérifie — les deux mêmes conditions qui décident si un retrait affecte un pull, de sorte qu’une recherche et un pull s’accordent sur la version qui constitue la réponse.

Un retrait qui ne remplit pas l’une ou l’autre condition ne change rien à ce qui est signalé. Un marqueur de sévérité consultative laisse sa version sélectionnable, et un marqueur dont la signature ne se vérifie pas n’est pas une affirmation sur laquelle cet espace de travail agit. Dans les deux cas, la version publiée la plus élevée est signalée exactement comme elle le serait sans aucun marqueur.

Une entité ayant une version retirée est toujours listée. Une colonne NOTES nomme les versions écartées et n’apparaît que dans un résultat qui a quelque chose à signaler. Une entité dont chaque version publiée est retirée est signalée avec (none) comme version et une note indiquant qu’il ne reste aucune version, plutôt que d’être supprimée du résultat — une entité omise serait impossible à distinguer d’une entité qui n’existe pas.

Passez --include-retracted pour signaler la version publiée la plus élevée quel que soit son statut de retrait, ce qui répond à « qu’est-ce qui est publié ? » plutôt qu’à « que dois-je utiliser ? ». Cela ne change que la version signalée ; la colonne NOTES nomme les versions retirées dans les deux cas.

Ce que lit une recherche est l’index local qu’écrit aggrega registry update ; elle signale donc ce que chaque registre déclarait lors de la dernière construction de cet index. Une version retirée depuis n’est pas encore enregistrée, et la ligne de fraîcheur écrite sur la sortie d’erreur standard indique le moment où chaque index a été construit.

Le résultat lisible par machine

--output json porte le même contrat dans deux champs :

  • version est la version qu’une résolution retiendrait. C’est la chaîne vide lorsque chaque version publiée est retirée, ce qui va de pair avec une liste retracted qui les nomme toutes.
  • retracted liste les versions écartées de ce choix, par ordre de version croissant. Le champ est absent lorsque rien n’a été écarté.

Un consommateur qui veut savoir quelle version il obtiendrait lit version. La déduire plutôt du tableau deprecations revient à réimplémenter les conditions de sévérité et de signature, et une seconde implémentation de ces conditions peut très bien être en désaccord avec celle qu’applique le compilateur ; retracted rapporte le résultat que ces conditions ont déjà produit.

Chaque enregistrement contient également published : chaque version que l’index a enregistrée, par ordre de version croissant, chacune avec le manifestDigest vers lequel son tag se résolvait lors de la construction de l’index et, lorsque la politique de confiance de cet espace de travail a vérifié la signature propre de cette version, son signer — parmi plusieurs signatures qui se vérifient, celle que le journal de transparence a enregistrée le plus tôt. Une version sans signer ne porte aucune signature vérifiée par cette politique, et rien de plus n’en est dit. Un consommateur qui lit le contenu d’une version l’adresse par ce digest — par exemple aggrega inspect oci://<host>/<repository>@<digest> — de sorte que ce qu’il lit, ce sont les octets que l’index a enregistrés, quoi qu’il advienne du tag par la suite.

Lorsque quelque chose enregistre la date de publication d’une version, son entrée contient également publishedAt, un horodatage RFC 3339 en UTC à la seconde près, et publishedAtSource, qui indique d’où il provient. transparency-log est le moment où un journal de transparence a enregistré la signature keyless de la version, que la politique de confiance de cet espace de travail a vérifiée avec la promesse signée du journal concernant ce moment — la signature du signer, la plus ancienne de celles qui se vérifient, de sorte que signer de nouveau une version ne déplace ni l’une ni l’autre. publisher est le moment que la publication a déclaré à côté de ce qu’elle a publié, selon l’horloge propre de la machine qui publie, que rien n’atteste. Les deux sont tenus séparés afin qu’un consommateur qui trie par date puisse encore distinguer une heure attestée d’une heure déclarée. Une version qui n’a ni l’une ni l’autre ne porte aucune date, et rien de plus n’en est dit ; voir aggrega registry update pour savoir quand chacune est enregistrée.