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:
aggrega scaffold --example quickstart-webDepois, 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 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/postgresecore/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.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 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 }.