Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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:

Terminal window
aggrega scaffold --example quickstart-web

Poi stampa i prossimi comandi da eseguire:

Terminal window
cd quickstart-web
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait
# then open http://127.0.0.1:8080/ in your browser

Cinque 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/postgres e core/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.0

La 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 }.