I file di un build
Questa pagina spiega un’unica idea, quale file di un build dice cosa, e non è un’area di lavoro eseguibile. Un’app web con PostgreSQL, costruita un passo alla volta la mostra in un’area di lavoro che compili tu; scrivila in una cartella tua con:
aggrega scaffold --example quickstart-webPoi stampa i prossimi comandi da eseguire:
cd quickstart-webcd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browserCinque tipi di file, ognuno con un solo autore
Un build legge cinque tipi di file. Ognuno dice una cosa sola e, in un team tipico, ognuno ha il proprio autore:
- un Component dice che cos’è un tipo di componente: i valori che uno sviluppatore può impostare, le impostazioni di infrastruttura che un operatore può impostare, ciò che pubblica ai componenti che si connettono a esso e i socket attraverso cui si connette. Il catalogo della libreria standard contiene i Components di cui la maggior parte delle applicazioni ha bisogno, come
core/datastore/postgresecore/compute/server, quindi di solito un’area di lavoro non ne scrive nessuno; - un Aggregate è dello sviluppatore: quali componenti ha l’applicazione e a cosa si connette ciascuno;
- una Recipe trasforma un tipo di componente in file per uno strumento — un servizio Compose, un chart Helm, un modulo Terraform;
- un Manifest sceglie quale Recipe realizza ciascun tipo di componente per una destinazione;
- una Release nomina un Aggregate e un Manifest e fornisce le impostazioni di un ambiente. È ciò che compili:
aggrega build --release release.yaml.
La suddivisione è un’indicazione: una sola persona può scriverli tutti e cinque, e il build accetta qualunque di essi purché ciascuno sia valido.
L’Aggregate: i componenti e le loro connessioni
Il primo passo dell’esempio è un’applicazione web con il suo database. Il suo Aggregate, da 1/aggregate.yaml senza i commenti:
spec: components: web: type: core/compute/server features: db_password: type: core/secret-value values: key: PGPASSWORD origin: "${QUICKSTART_DB_PASSWORD}" uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: database
db: type: core/datastore/postgres features: password: type: core/secret-value values: key: POSTGRES_PASSWORD origin: "${QUICKSTART_DB_PASSWORD}"Qui nulla nomina una porta, un host, un namespace o uno strumento. web si connette a db attraverso il suo socket database, e la lista inject dice quale variabile dell’applicazione riceve ciascuna voce che il database pubblica: from: nomina la voce, in: la variabile.
Una connessione è una stringa, convogliata
La Recipe del database pubblica host, port, user e database perché la connessione li legga. Quale indirizzo contiene host dipende dalla Recipe scelta dal Manifest: il nome di un servizio dove il database gira accanto all’applicazione, una stringa puntatore che uno strumento di provisioning risolve per un database gestito, oppure l’indirizzo di un server che esiste già. Il build copia ogni stringa pubblicata nella variabile nominata dall’Aggregate e non la interpreta: non risolve mai un indirizzo né verifica che sia raggiungibile.
Il Manifest e la Release
Il Manifest, da 1/manifest.yaml, associa ciascun tipo di componente, e gli allegati per le password, alla Recipe che lo realizza su Docker Compose:
spec: mappings: components: type: core/compute/server:1.1.0: compose/server:2.0.0 core/datastore/postgres:1.0.0: compose/postgres:1.0.0 features: type: core/secret-value:1.0.0: compose/dotenv-secret:1.0.0La Release, da 1/release.yaml, nomina l’Aggregate e il Manifest e fornisce ciò che solo un ambiente conosce, qui l’immagine che l’applicazione esegue, la porta su cui è in ascolto e la porta su cui Docker Compose la pubblica, sull’indirizzo di loopback della tua macchina (con il digest dell’immagine abbreviato):
spec: aggregate: quickstart-web manifest: quickstart-web-compose components: web: infra: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:… port: 8080 published_port: 8080 db: {}I passi successivi dell’esempio lo ampliano: una cache Redis accanto al database, poi gli stessi componenti su AWS tramite Terraform, poi i backup del database.
Parametri: un solo Aggregate, molti ambienti
Un valore che differisce tra gli ambienti si dichiara nell’Aggregate come parametro tipizzato, si referenzia dove viene usato e viene fornito da ciascuna Release. In Un’attività eseguita su richiesta, l’Aggregate dichiara la pianificazione del suo report:
spec: parameters: report_schedule: type: string default: "" components: report: type: core/compute/task values: schedule: "{{ .parameters.report_schedule }}"e una Release lo soddisfa:
spec: parameters: report_schedule: "30 2 * * 1-5"Il build verifica ogni valore fornito da una Release rispetto al tipo del parametro prima di riempire il template. Una Release non scrive mai direttamente i values di un componente: soddisfa i parametri che l’Aggregate espone, così l’Aggregate resta l’unico posto che dice quali valori variano a seconda dell’ambiente. Una Release può anche leggere i propri parametri da un file dedicato, parameters: { $import: ./env/prod-values.yaml }.