Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Los archivos de una compilación

Esta página explica una sola idea, qué archivo de una compilación dice qué, y no es un espacio de trabajo ejecutable. Una aplicación web con PostgreSQL, construida paso a paso la muestra en un espacio de trabajo que compilas; escríbelo en una carpeta propia con:

Terminal window
aggrega scaffold --example quickstart-web

Después imprime los comandos que hay que ejecutar a continuación:

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

Cinco tipos de archivo, cada uno con un solo autor

Una compilación lee cinco tipos de archivo. Cada uno dice una sola cosa y, en un equipo típico, cada uno tiene su propio autor:

  • un Component dice qué es un tipo de componente: los valores que un desarrollador puede establecer, los ajustes de infraestructura que un operador puede establecer, lo que publica a los componentes que se conectan a él y los sockets a través de los que se conecta. El catálogo de la biblioteca estándar incluye los Components que necesitan la mayoría de las aplicaciones, como core/datastore/postgres y core/compute/server, por lo que un espacio de trabajo normalmente no escribe ninguno;
  • un Aggregate es del desarrollador: qué componentes tiene la aplicación y a qué se conecta cada uno;
  • una Recipe convierte un tipo de componente en archivos para una herramienta — un servicio de Compose, un chart de Helm, un módulo de Terraform;
  • un Manifest elige qué Recipe realiza cada tipo de componente para un destino;
  • una Release nombra un Aggregate y un Manifest y proporciona los ajustes de un entorno. Es lo que compilas: aggrega build --release release.yaml.

La división es orientativa: una sola persona puede escribir los cinco, y la compilación acepta cualquiera de ellos siempre que cada uno sea válido.

El Aggregate: los componentes y sus conexiones

El primer paso del ejemplo es una aplicación web y su base de datos. Su Aggregate, de 1/aggregate.yaml sin sus comentarios:

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}"

Nada aquí nombra un puerto, un host, un namespace ni una herramienta. web se conecta a db a través de su socket database, y la lista inject indica qué variable de la aplicación recibe cada entrada que publica la base de datos: from: nombra la entrada, in: la variable.

Una conexión es una cadena, canalizada

La Recipe de la base de datos publica host, port, user y database para que la conexión los lea. Qué dirección contiene host depende de la Recipe que eligió el Manifest: el nombre de un servicio cuando la base de datos se ejecuta junto a la aplicación, una cadena puntero que una herramienta de aprovisionamiento resuelve para una base de datos gestionada, o la dirección de un servidor que ya existe. La compilación copia cada cadena publicada en la variable que nombró el Aggregate y no la interpreta: nunca resuelve una dirección ni comprueba que sea accesible.

El Manifest y la Release

El Manifest, de 1/manifest.yaml, vincula cada tipo de componente, y los adjuntos de contraseña, a la Recipe que lo realiza en 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, de 1/release.yaml, nombra el Aggregate y el Manifest y proporciona lo que solo un entorno conoce, aquí la imagen que ejecuta la aplicación, el puerto en el que escucha y el puerto en el que Docker Compose la publica, en la dirección de loopback de tu máquina (con el digest de la imagen abreviado):

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: {}

Los pasos posteriores del ejemplo lo amplían: una caché Redis junto a la base de datos, después los mismos componentes en AWS mediante Terraform, y después las copias de seguridad de la base de datos.

Parámetros: un solo Aggregate, muchos entornos

Un valor que difiere entre entornos se declara en el Aggregate como un parámetro tipado, se referencia donde se usa y lo proporciona cada Release. En Una tarea ejecutada bajo demanda, el Aggregate declara la programación de su informe:

spec:
parameters:
report_schedule:
type: string
default: ""
components:
report:
type: core/compute/task
values:
schedule: "{{ .parameters.report_schedule }}"

y una Release lo satisface:

spec:
parameters:
report_schedule: "30 2 * * 1-5"

La compilación comprueba cada valor que proporciona una Release contra el tipo del parámetro antes de rellenar la plantilla. Una Release nunca escribe por sí misma los values de un componente: satisface los parámetros que expone el Aggregate, de modo que el Aggregate sigue siendo el único lugar que dice qué valores varían según el entorno. Una Release también puede leer sus parámetros de un archivo propio, parameters: { $import: ./env/prod-values.yaml }.