Esempi eseguibili
Per iniziare, Primi passi installa Aggrega e percorre passo per passo due di questi esempi.
Workspace completi, di cui è possibile fare il fork, che puoi compilare con la CLI aggrega. Ciascuno è una directory autonoma — un Aggregate scritto dallo sviluppatore e una o più coppie Release/Manifest — il cui build non richiede alcuna configurazione oltre a quella che la sua pagina indica. Per trovarne uno in base al prodotto che distribuisce o a ciò che mostra, usa Esempi per prodotto e capacità, che elenca ogni esempio presente qui.
Gli esempi si presentano in due modalità — i due estremi di un unico percorso didattico:
-
Consumo — il workspace fa riferimento a entità del catalogo della libreria standard e scrive localmente solo il proprio contenuto didattico specifico. Il suo build non richiede il flag
--catalog:Terminal window aggrega build --release release.yamlDa dove vengono lette quelle entità referenziate dipende dal workspace. Una directory
catalog/nella radice del workspace viene letta che qualcosa la nomini o no, quindi un workspace che scrive contenuto didattico proprio può semplicemente tenerlo lì. Un workspace che contiene un.aggrega-config.yamllegge anche ogni directory elencata sottocatalog_dirs, ciascuna una directory in cui tiene entità. Le directory elencate vengono cercate per prime ecatalog/per ultima, e nella pila vince la prima corrispondenza, quindi un’entità in una directory cercata prima oscura una con la stessa identità in una cercata dopo. Ciò che nessuna directory locale dichiara — le entità della libreria standard — si risolve dal registry che la configurazione indica comedefault_registry,hub.aggrega.ai. Un workspace che non scrive nulla localmente non ha bisogno di alcuna voce locale, e uno che non contiene né una directorycatalog/né un.aggrega-config.yamlsi risolve interamente tramite il registry configurato. Scriverecatalog_dirscome elenco vuoto indica che il workspace non ha alcun catalogo locale. Ogni percorso incatalog_dirsnomina una directory all’interno del workspace, quindi una copia dell’intero workspace portata altrove esegue il build così com’è.Un workspace con più destinazioni che tiene un catalogo separato per ciascuna destinazione nomina le directory di ciascuna destinazione sotto
workspace.releases, indicizzate per il rispettivo file di Release, così ogni Release esegue il build sul proprio catalogo. -
Scrittura — il workspace costruisce da zero le entità del catalogo (Components, Features, Recipes) in directory locali
catalog-*/.mariadb-adminerè l’esempio di scrittura svolto; le entità che costruisce sono dello stesso tipo di quelle che gli esempi di consumo consumano.
Esegui il build di una release per esecuzione con aggrega build --release <release file>; la pagina di ciascun esempio fornisce i propri comandi. Il workspace fornisce il proprio catalogo come descritto sopra; passa tu stesso --catalog per una directory di catalogo che il workspace non nomina, come mostrano le pagine che ne hanno bisogno.
I lockfile vengono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno e il primo build ne richiede uno. aggrega build è di sola lettura per impostazione predefinita: senza lockfile si arresta e nomina le due strade possibili. Passa --auto-pull per quel primo build — aggrega build --release release.yaml --auto-pull — per risolvere il lockfile durante il build; eseguire una volta in anticipo aggrega pull --release <release file> fa lo stesso e permette a ogni build successivo di essere eseguito senza flag.
In un checkout del repository della documentazione, la maggior parte dei workspace contiene anche uno script di supporto build-release.sh tramite il quale eseguono il build i controlli propri del repository. Esegue aggrega build per una release, mostrando prima il comando, e riporta quale binario aggrega ha usato e da dove proviene quel binario; imposta AGGREGA_BIN per scegliere il binario. Una copia scritta da aggrega scaffold --example contiene lo script di supporto senza lo script condiviso che esso chiama, quindi esegui il build di una copia di questo tipo direttamente con aggrega build.
Dove un esempio qui nomina un checkout del catalogo della libreria standard, Importazione indica dove procurarsene uno.
Questi completano le pagine concettuali descritte in Panoramica degli esempi: una pagina concettuale spiega un’idea e rimanda al workspace che la mostra; i workspace qui sono stack completi di cui puoi eseguire il build e che puoi leggere e adattare.
Dove una pagina riporta ciò che un build ha prodotto, quel blocco è copiato da un’esecuzione reale così puoi confrontarvi il tuo output — e le righe omesse sono contrassegnate. Leggere l’output in queste pagine enuncia quella convenzione e il contrassegno che usa.
Non tutte le directory qui sono un singolo workspace. Gli esempi quickstart contengono un workspace per ogni passo, e gli esempi di import uno per ogni fase di un import, come descrive il paragrafo successivo. Una directory non contiene alcun workspace: policy-in-ci contiene due script di regole che leggono la directory di output di un build e la rifiutano quando viola una regola, con il passo di pipeline per ciascuno. Vengono eseguiti sugli output dei workspace qui presenti, e sui tuoi.
Ogni esempio import-* — elencato sotto la capacità import in Esempi per prodotto e capacità — conserva un progetto scritto in un altro formato così come lo trova aggrega import, in due cartelle: source/, il progetto, il .aggrega-config.yaml che lo rende un workspace e il file delle risposte da cui l’import legge i valori che nessun sorgente può contenere; e draft/, i file scritti dall’import, invariati, un workspace la cui build va a buon fine così come è scritto, con ciò che ha stampato sullo standard output (stdout.txt) e sullo standard error (import.txt). La sua guida passo passo in Importazione insegna ogni fase. Il suo check.sh esegue lo script condiviso scripts/check-import-example.sh di questo repository, che esegue di nuovo l’import, confronta ciò che scrive e stampa con draft/ e i blocchi citati dalla guida con i file dell’esempio, poi convalida la Release redatta ed esegue la sua build.
L’ordine didattico
Ogni esempio qui ha un posto in un unico ordine didattico, dato da tier e position nella sua intestazione: fascia per fascia, nell’ordine indicato dall’elenco delle fasce, e dal più semplice all’interno di ciascuna fascia. In ordine didattico elenca ogni esempio in quel modo, e la sezione Esempi della barra laterale segue lo stesso ordine. Leggi le fasce dall’alto in basso, oppure passa a quella che corrisponde a ciò che stai facendo; per trovare invece un esempio in base a ciò che distribuisce o a ciò che mostra, la stessa pagina li elenca per prodotto e per funzionalità.
Un build può anche eseguire plugin su ciò che renderizza — vedi Quando ricorrere a un passo della pipeline.
L’intestazione di ogni esempio
Il README di ogni esempio si apre con una breve intestazione, scritta come front matter YAML, che dice che cos’è l’esempio: il suo livello, il suo posto nell’ordine didattico, i prodotti che distribuisce e ciò che mostra. Esempi per prodotto e capacità è generato da queste intestazioni.
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level è uno di questi livelli:
start— il livello Solo catalogo: assemblato da entità del catalogo, senza nulla di scritto tranne l’Aggregate, il Manifest e la Release.authoring— il livello Scrittura: scrive un Component, una Feature o una Recipe, o mostra come è fatto.advanced— il livello Avanzato: confini, policy di governance, Features guidate dalle annotazioni e stack cloud assemblati.
tier è la parte dell’ordine didattico a cui appartiene l’esempio, una di queste fasce, insegnate in quest’ordine:
start-here— Inizia da qui: i due esempi che la guida «Per iniziare» fa crescere un passo alla volta, poi i due esempi di partenza per il cloud.catalog-only— Solo catalogo: assemblato da entità del catalogo, senza nulla di scritto a parte l’Aggregate, il Manifest e la Release.authoring— Creazione: scrive un Component, una Feature o una Recipe propri, oppure mostra come se ne struttura uno.advanced— Avanzato: confini, policy di governance, Features guidate da annotazioni e stack cloud assemblati, diversi dei quali combinati in un’unica build.importers— Importatori: un progetto scritto in un altro formato, trasformato in bozze di file Aggrega daaggrega import, poi revisionato e compilato.
position è il posto dell’esempio all’interno della sua fascia, un numero intero positivo che nessun altro esempio di quella fascia occupa; una fascia elenca i suoi esempi dalla posizione più bassa in su, prima i più semplici.
products elenca ogni Component del catalogo che l’esempio distribuisce, con il nome che porta la sua voce di catalogo. Un componente di calcolo generico (core/compute/server, ad esempio) e un’entità che l’esempio dichiara per sé non vengono elencati, quindi un esempio può non elencarne nessuno.
shows elenca ciò che l’esempio dimostra, ogni voce presa da questo elenco:
multi-target— un Aggregate costruito per due o più destinazioni, o realizzato in due o più modi.recipe-selection— il Manifest che sceglie quale Recipe realizza un componente, o quale FeatureRecipe realizza un’associazione: per tipo, per istanza o per destinazione.modules— un Aggregate del catalogo importato come modulo.connections— componenti collegati tramite socketuses, con valori convogliati attraverso ciascun arco.credentials— associazioni di credenziali e il modo in cui ciascuna destinazione le consegna.parameters— valori portati in parametri che una Release soddisfa.features— Features associate per qualcosa di diverso da una credenziale, come l’instradamento, il monitoraggio, un budget, una cache o il mascheramento.boundaries— componenti o moduli collocati in confini, e ciò che passa tra di essi.policy— policy di governance che accetta o rifiuta un build, durante il build o sul suo output.guardrails— una Release destinata ad arrestarsi, e il messaggio con cui si arresta.catalog-authoring— un Component, una Feature o una Recipe scritti per l’esempio, tenuti accanto a esso o pubblicati nel catalogo.cloud-infrastructure— output Terraform o CloudFormation per servizi cloud gestiti.external-sources— una Recipe che recupera ciò che renderizza: un chart upstream, un repository git o un modulo.import— un progetto scritto in un altro formato, trasformato in bozze di file Aggrega daaggrega import, poi revisionato e compilato.
Un esempio elenca almeno un prodotto o una capacità, così l’indice può collocarlo. Il suo README contiene anche una sezione ## Scaffold the example, con aggrega scaffold --example <name> nel suo primo blocco di comandi e cd <name> nel secondo, seguita direttamente da una sezione ## Build il cui primo blocco di comandi è ciò che aggrega scaffold --example stampa come passo successivo da eseguire dopo quel cd. scripts/gen-examples-index.sh --check, eseguito dalla radice di questo repository, verifica ogni intestazione rispetto a questi elenchi, rifiuta un esempio a cui manca una delle due sezioni, e uno che non ha né un check.sh eseguibile né un build-release.sh, e conferma che l’indice è aggiornato; eseguilo senza --check per scrivere di nuovo l’indice.