Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Os ficheiros de uma compilação

Esta página explica uma única ideia, que ficheiro de uma compilação diz o quê, e não é um espaço de trabalho executável. Uma aplicação web com PostgreSQL, construída um passo de cada vez mostra-a num espaço de trabalho que se compila; pode escrevê-lo numa pasta própria com:

Terminal window
aggrega scaffold --example quickstart-web

Depois, imprime os próximos comandos a executar:

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 ficheiro, cada um com um autor

Uma compilação lê cinco tipos de ficheiro. Cada um diz uma coisa e, numa equipa típica, cada um tem o seu próprio autor:

  • um Component diz o que é um tipo de componente: os valores que um programador pode definir, as definições de infraestrutura que um operador pode configurar, o que publica para os componentes que se ligam a ele e os sockets através dos quais se liga. O catálogo da biblioteca padrão traz os Components de que a maioria das aplicações precisa, como core/datastore/postgres e core/compute/server, pelo que um espaço de trabalho normalmente não escreve nenhum;
  • um Aggregate é do programador: que componentes a aplicação tem e a que se liga cada um;
  • uma Recipe transforma um tipo de componente em ficheiros para uma ferramenta — um serviço Compose, um chart Helm, um módulo Terraform;
  • um Manifest escolhe que Recipe realiza cada tipo de componente para um destino;
  • uma Release nomeia um Aggregate e um Manifest e fornece as definições de um ambiente. É o que se compila: aggrega build --release release.yaml.

A divisão é uma orientação: uma só pessoa pode escrever os cinco, e a compilação aceita qualquer um deles desde que cada um seja válido.

O Aggregate: os componentes e as suas ligações

O primeiro passo do exemplo é uma aplicação web e a sua base de dados. O seu Aggregate, de 1/aggregate.yaml sem os comentários:

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 aqui nomeia uma porta, um host, um namespace ou uma ferramenta. web liga-se a db através do seu socket database, e a lista inject diz que variável da aplicação recebe cada entrada que a base de dados publica: from: nomeia a entrada, in: a variável.

Uma ligação é uma string, encaminhada

A Recipe da base de dados publica host, port, user e database para a ligação ler. O endereço que host contém depende da Recipe que o Manifest escolheu: o nome de um serviço quando a base de dados corre ao lado da aplicação, uma string de ponteiro que uma ferramenta de aprovisionamento resolve para uma base de dados gerida, ou o endereço de um servidor que já existe. A compilação copia cada string publicada para a variável que o Aggregate nomeou e não a interpreta: nunca resolve um endereço nem verifica se está acessível.

O Manifest e a Release

O Manifest, de 1/manifest.yaml, associa cada tipo de componente, e os anexos de palavras-passe, à Recipe que o realiza no 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

A Release, de 1/release.yaml, nomeia o Aggregate e o Manifest e fornece o que só um ambiente sabe, aqui a imagem que a aplicação executa, a porta em que escuta e a porta em que o Docker Compose a publica, no endereço de loopback da máquina (com o digest da imagem 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: {}

Os passos seguintes do exemplo ampliam-no: uma cache Redis ao lado da base de dados, depois os mesmos componentes na AWS através do Terraform, depois as cópias de segurança da base de dados.

Parâmetros: um Aggregate, muitos ambientes

Um valor que difere entre ambientes é declarado no Aggregate como um parâmetro tipado, referenciado onde é usado e fornecido por cada Release. Em Uma tarefa executada a pedido, o Aggregate declara o agendamento do seu relatório:

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

e uma Release preenche-o:

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

A compilação verifica cada valor que uma Release fornece face ao tipo do parâmetro antes de preencher o modelo. Uma Release nunca escreve ela própria os values de um componente: preenche os parâmetros que o Aggregate expõe, pelo que o Aggregate continua a ser o único sítio que diz que valores variam consoante o ambiente. Uma Release também pode ler os seus parâmetros de um ficheiro próprio, parameters: { $import: ./env/prod-values.yaml }.