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

Exemples exécutables

Pour commencer, Premiers pas installe Aggrega et parcourt pas à pas deux de ces exemples.

Des workspaces complets, que l’on peut forker, que vous pouvez compiler avec la CLI aggrega. Chacun est un répertoire autonome — un Aggregate rédigé par le développeur et une ou plusieurs paires Release/Manifest — dont le build ne demande aucune configuration au-delà de ce que nomme sa page. Pour en trouver un par le produit qu’il déploie ou par ce qu’il montre, utilisez Exemples par produit et par capacité, qui liste chaque exemple présent ici.

Les exemples se présentent sous deux modes — les deux extrémités d’un même parcours d’apprentissage :

  • Consommation — le workspace référence des entités du catalogue de la bibliothèque standard et ne rédige localement que son propre contenu pédagogique. Son build se fait sans le flag --catalog :

    Terminal window
    aggrega build --release release.yaml

    L’endroit d’où ces entités référencées sont lues dépend du workspace. Un répertoire catalog/ à la racine du workspace est lu, que quelque chose le nomme ou non, de sorte qu’un workspace qui rédige son propre contenu pédagogique peut simplement l’y conserver. Un workspace qui contient un .aggrega-config.yaml lit aussi chaque répertoire listé sous catalog_dirs, chacun étant un répertoire où il conserve des entités. Les répertoires listés sont parcourus en premier et catalog/ en dernier, et la pile retient la première occurrence, de sorte qu’une entité d’un répertoire parcouru plus tôt masque une entité de même identité d’un répertoire parcouru plus tard. Ce qu’aucun répertoire local ne déclare — les entités de la bibliothèque standard — se résout depuis le registre que la configuration nomme default_registry, hub.aggrega.ai. Un workspace qui ne rédige rien localement n’a besoin d’aucune entrée locale, et un workspace qui ne contient ni répertoire catalog/ ni .aggrega-config.yaml se résout entièrement par le registre configuré. Écrire catalog_dirs sous forme de liste vide indique que le workspace n’a aucun catalogue local. Chaque chemin de catalog_dirs nomme un répertoire à l’intérieur du workspace, de sorte qu’une copie de tout le workspace emportée ailleurs effectue son build telle quelle.

    Un workspace multi-cible qui conserve un catalogue distinct par cible nomme les répertoires de chaque cible sous workspace.releases, indexés par leur fichier de Release, de sorte que chaque Release effectue son build avec son propre catalogue.

  • Rédaction — le workspace construit les entités du catalogue (Components, Features, Recipes) à partir de zéro dans des répertoires locaux catalog-*/. mariadb-adminer est l’exemple de rédaction détaillé ; les entités qu’il construit sont du même type que celles que consomment les exemples de consommation.

Effectuez le build d’une release par exécution avec aggrega build --release <release file> ; la page de chaque exemple donne ses propres commandes. Le workspace fournit son catalogue comme décrit ci-dessus ; passez vous-même --catalog pour un répertoire de catalogue que le workspace ne nomme pas, comme le montrent les pages qui en ont besoin.

Les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun et que le premier build en a besoin d’un. aggrega build est en lecture seule par défaut : sans lockfile, il s’arrête et nomme les deux façons de poursuivre. Passez --auto-pull pour ce premier build — aggrega build --release release.yaml --auto-pull — afin de résoudre le lockfile pendant le build ; exécuter une fois au préalable aggrega pull --release <release file> produit le même effet et permet à chaque build ultérieur de s’exécuter sans flag.

Dans un checkout du dépôt de la documentation, la plupart des workspaces contiennent aussi un script d’aide build-release.sh par lequel passent les propres vérifications du dépôt pour effectuer le build. Il exécute aggrega build pour une release, en affichant d’abord la commande, et indique quel binaire aggrega il a utilisé et d’où provient ce binaire ; définissez AGGREGA_BIN pour choisir le binaire. Une copie écrite par aggrega scaffold --example contient le script d’aide sans le script partagé qu’il appelle ; effectuez donc le build d’une telle copie directement avec aggrega build.

Là où un exemple de cette page nomme un checkout du catalogue de la bibliothèque standard, Importation indique où en obtenir un.

Ils complètent les pages de concept décrites dans Vue d’ensemble des exemples : une page de concept explique une idée et renvoie au workspace qui la montre ; les workspaces présentés ici sont des piles complètes dont vous pouvez effectuer le build, que vous pouvez lire et adapter.

Lorsqu’une page affiche ce qu’un build a produit, ce bloc est copié d’une exécution réelle afin que vous puissiez y comparer votre propre sortie — et toute ligne omise est signalée. Lire la sortie sur ces pages énonce cette convention et la marque qu’elle utilise.

Les répertoires ici ne sont pas tous un seul workspace. Les exemples quickstart contiennent un workspace par étape, et les exemples d’import un par stade d’un import, comme le décrit le paragraphe suivant. Un répertoire ne contient aucun workspace : policy-in-ci contient deux scripts de règles qui lisent le répertoire de sortie d’un build et le refusent lorsqu’il enfreint une règle, avec l’étape de pipeline de chacun. Ils s’exécutent sur les sorties des workspaces présentés ici, et sur les vôtres.

Chaque exemple import-* — listé sous la capacité import dans Exemples par produit et capacité — conserve un projet écrit dans un autre format tel que aggrega import le trouve, dans deux dossiers : source/, le projet, le .aggrega-config.yaml qui en fait un workspace et le fichier de réponses dans lequel l’import lit les valeurs qu’aucune source ne peut contenir ; et draft/, les fichiers que l’import a écrits, inchangés, un workspace qui se construit tel qu’il est écrit, avec ce qu’il a affiché sur la sortie standard (stdout.txt) et sur la sortie d’erreur standard (import.txt). Son guide pas à pas sous Importation enseigne chaque étape. Son check.sh exécute le script partagé scripts/check-import-example.sh de ce dépôt, qui importe à nouveau, compare ce qu’il écrit et affiche avec draft/ et les blocs que cite le guide avec les fichiers de l’exemple, puis valide et construit la Release rédigée.

L’ordre pédagogique

Chaque exemple présenté ici a une place dans un ordre pédagogique unique, donnée par tier et position dans son en-tête : niveau par niveau, dans l’ordre que donne la liste des niveaux, et le plus simple en premier au sein de chaque niveau. Dans l’ordre pédagogique liste chaque exemple de cette façon, et la section Exemples de la barre latérale suit le même ordre. Lisez les niveaux de haut en bas, ou passez directement à celui qui correspond à ce que vous faites ; pour trouver plutôt un exemple selon ce qu’il déploie ou ce qu’il montre, la même page les liste par produit et par capacité.

Un build peut aussi exécuter des plugins sur ce qu’il rend — voir Quand recourir à une étape de pipeline.

L’en-tête de chaque exemple

Le README de chaque exemple commence par un court en-tête, écrit sous forme de front matter YAML, qui dit ce qu’est l’exemple : son niveau, sa place dans l’ordre d’apprentissage, les produits qu’il déploie et ce qu’il montre. Exemples par produit et par capacité est généré à partir de ces en-têtes.

---
example:
level: start
tier: catalog-only
position: 1
products: [core/datastore/mariadb, core/devtool/adminer]
shows: [connections, credentials]
---

level est l’un de ces niveaux :

  • start — le niveau Catalogue uniquement : assemblé à partir d’entités du catalogue, sans rien rédiger d’autre que l’Aggregate, le Manifest et la Release.
  • authoring — le niveau Rédaction : rédige un Component, une Feature ou une Recipe, ou montre comment l’un d’eux est structuré.
  • advanced — le niveau Avancé : frontières, politique de gouvernance, Features pilotées par les annotations et piles cloud assemblées.

tier est la partie de l’ordre d’apprentissage à laquelle appartient l’exemple, l’un de ces paliers, enseignés dans cet ordre :

  • start-here — Commencer ici : les deux exemples que le guide « Premiers pas » fait grandir une étape à la fois, puis les deux exemples de départ pour le cloud.
  • catalog-only — Catalogue uniquement : assemblé à partir d’entités du catalogue, sans rien d’écrit en dehors de l’Aggregate, du Manifest et de la Release.
  • authoring — Création : écrit un Component, une Feature ou une Recipe qui lui est propre, ou montre comment l’un d’eux est structuré.
  • advanced — Avancé : frontières, politiques de gouvernance, Features pilotées par annotation et stacks cloud assemblées, dont plusieurs sont combinées dans un même build.
  • importers — Importateurs : un projet écrit dans un autre format, transformé en brouillons de fichiers Aggrega par aggrega import, puis relu et compilé.

position est la place de l’exemple au sein de son palier, un nombre entier positif qu’aucun autre exemple de ce palier ne prend ; un palier liste ses exemples de la position la plus basse vers le haut, le plus simple en premier.

products liste chaque Component du catalogue que l’exemple déploie, sous le nom que porte son entrée de catalogue. Un composant de calcul générique (core/compute/server, par exemple) et une entité que l’exemple déclare pour lui-même ne sont pas listés, de sorte qu’un exemple peut n’en lister aucun.

shows liste ce que l’exemple démontre, chaque entrée étant prise dans cette liste :

  • multi-target — un Aggregate construit pour deux cibles ou plus, ou réalisé de deux façons ou plus.
  • recipe-selection — le Manifest qui choisit quelle Recipe réalise un composant, ou quelle FeatureRecipe réalise un rattachement : par type, par instance ou par cible.
  • modules — un Aggregate du catalogue importé comme module.
  • connections — des composants reliés par des sockets uses, avec des valeurs acheminées à travers chaque arête.
  • credentials — des rattachements d’informations d’identification et la façon dont chaque cible les livre.
  • parameters — des valeurs hissées en paramètres qu’une Release fournit.
  • features — des Features rattachées pour autre chose que des informations d’identification, comme le routage, la supervision, un budget, un cache ou le masquage.
  • boundaries — des composants ou des modules placés dans des frontières, et ce qui passe de l’une à l’autre.
  • policy — une politique de gouvernance qui accepte ou refuse un build, pendant le build ou sur sa sortie.
  • guardrails — une Release destinée à s’arrêter, et le message avec lequel elle s’arrête.
  • catalog-authoring — un Component, une Feature ou une Recipe rédigé pour l’exemple, conservé à côté de lui ou publié dans le catalogue.
  • cloud-infrastructure — une sortie Terraform ou CloudFormation pour des services cloud gérés.
  • external-sources — une Recipe qui récupère ce qu’elle rend : un chart amont, un dépôt git ou un module.
  • import — un projet écrit dans un autre format, transformé en brouillons de fichiers Aggrega par aggrega import, puis relu et compilé.

Un exemple liste au moins un produit ou une capacité, afin que l’index puisse le placer. Son README comporte aussi une section ## Scaffold the example, contenant aggrega scaffold --example <name> dans son premier bloc de commandes et cd <name> dans le deuxième, directement suivie d’une section ## Build dont le premier bloc de commandes est ce que aggrega scaffold --example affiche comme étape suivante à exécuter après ce cd. scripts/gen-examples-index.sh --check, exécuté depuis la racine de ce dépôt, vérifie chaque en-tête par rapport à ces listes, refuse un exemple auquel manque l’une des deux sections, ainsi qu’un exemple qui n’a ni check.sh exécutable ni build-release.sh, et confirme que l’index est à jour ; exécutez-le sans --check pour écrire à nouveau l’index.