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

Os arquivos de um build

Esta página explica uma única ideia, qual arquivo de um build diz o quê, e não é um espaço de trabalho executável. Um app web com PostgreSQL, construído um passo de cada vez mostra isso em um espaço de trabalho que você compila; escreva-o em uma pasta sua com:

Terminal window
aggrega scaffold --example quickstart-web

Em seguida ele 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 arquivo, cada um com um autor

Um build lê cinco tipos de arquivo. Cada um diz uma coisa e, em uma equipe típica, cada um tem seu próprio autor:

  • um Component diz o que é um tipo de componente: os valores que um desenvolvedor pode definir, as configurações de infraestrutura que um operador pode definir, o que ele publica para os componentes que se conectam a ele e os sockets pelos quais ele se conecta. 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, então um espaço de trabalho normalmente não escreve nenhum;
  • um Aggregate é do desenvolvedor: quais componentes a aplicação tem e ao que cada um se conecta;
  • uma Recipe transforma um tipo de componente em arquivos para uma ferramenta — um serviço do Compose, um chart do Helm, um módulo do Terraform;
  • um Manifest escolhe qual Recipe realiza cada tipo de componente para um destino;
  • uma Release nomeia um Aggregate e um Manifest e fornece as configurações de um ambiente. É o que você compila: aggrega build --release release.yaml.

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

O Aggregate: os componentes e suas conexões

O primeiro passo do exemplo é uma aplicação web e seu banco de dados. 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 se conecta a db pelo seu socket database, e a lista inject diz qual variável da aplicação recebe cada entrada que o banco de dados publica: from: nomeia a entrada, in: a variável.

Uma conexão é uma string, canalizada

A Recipe do banco de dados publica host, port, user e database para a conexão ler. Qual endereço host contém depende da Recipe que o Manifest escolheu: o nome de um serviço quando o banco de dados roda ao lado da aplicação, uma string de ponteiro que uma ferramenta de provisionamento resolve para um banco de dados gerenciado, ou o endereço de um servidor que já existe. O build 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 ele está acessível.

O Manifest e a Release

O Manifest, de 1/manifest.yaml, vincula cada tipo de componente, e os anexos de senha, à 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 ela escuta e a porta em que o Docker Compose a publica, no endereço de loopback da sua 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 o ampliam: um cache Redis ao lado do banco de dados, depois os mesmos componentes na AWS via Terraform, depois os backups do banco 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 sob demanda, 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 o preenche:

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

O build verifica cada valor que uma Release fornece em relação ao tipo do parâmetro antes de preencher o template. Uma Release nunca escreve ela mesma os values de um componente: ela preenche os parâmetros que o Aggregate expõe, de modo que o Aggregate continua sendo o único lugar que diz quais valores variam por ambiente. Uma Release também pode ler seus parâmetros de um arquivo próprio, parameters: { $import: ./env/prod-values.yaml }.