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:
aggrega scaffold --example quickstart-webDespués imprime los comandos que hay que ejecutar a continuación:
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 browserCinco 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/postgresycore/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.0La 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 }.