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:
aggrega scaffold --example quickstart-webEm seguida ele imprime os próximos comandos a executar:
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 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/postgresecore/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.0A 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 }.