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

Importar um projeto Compose

Este passo a passo importa um pequeno projeto Compose — uma API, o banco de dados PostgreSQL em que ela guarda suas notas e um cache Redis — e compila o resultado para Docker Compose. A importação gera como rascunho cada arquivo que o build lê, levando adiante o que o arquivo Compose declara: as conexões da API com o banco de dados e o cache, o usuário e o nome do banco de dados, a senha como referência a variável e a tag de cada imagem. Cada arquivo e cada bloco de saída abaixo vêm de uma execução real; o projeto e cada etapa do passo a passo estão no exemplo import-compose, onde um script de verificação executa a importação novamente, compara o que ela grava, o que ela imprime e os blocos que esta página cita com os arquivos mantidos ali, e valida e compila o que a importação gravou.

Gerar o exemplo

Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example import-compose

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, que contém o que esta página importa e é onde a importação é executada:

Terminal window
cd import-compose

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando seu arquivo Compose: a API de um serviço de notas, seu banco de dados PostgreSQL e seu cache Redis.

O projeto

compose.yaml:

# A small notes service: its API, the PostgreSQL database it keeps the notes in,
# and the Redis cache in front of it.
name: notes
services:
api:
image: ghcr.io/example/notes-api:2.3.0
ports:
- "8080:8080"
environment:
DATABASE_HOST: db
DATABASE_USER: notes
DATABASE_NAME: notes
DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
CACHE_HOST: cache
depends_on:
- db
- cache
db:
image: postgres:16
environment:
POSTGRES_USER: notes
POSTGRES_DB: notes
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- db-data:/var/lib/postgresql/data
cache:
image: redis:7
volumes:
db-data:

Ao lado dele, um .aggrega-config.yaml torna a pasta um espaço de trabalho, de modo que a importação grava seus rascunhos ali:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside compose.yaml.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

A importação compara cada serviço com os Components do catálogo do espaço de trabalho, e --target gera como rascunho um Manifest a partir das Recipes do catálogo. O espaço de trabalho não indica nenhuma pasta de catálogo, então a importação lê o catálogo da biblioteca padrão do registro do qual busca seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que é identificado pelo digest no arquivo de registro que a importação grava ao lado dos rascunhos. Um espaço de trabalho que indica as próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS ou em workspace.catalog_dirs — importa em relação a elas.

O arquivo de respostas

Um build para Docker Compose não precisa de nada que o arquivo Compose não declare, então esta importação não pergunta nada. Um build do mesmo projeto para Kubernetes, com --target helm, precisa de um valor que nenhum arquivo Compose contém: o nome do Secret do Kubernetes do qual a senha do banco de dados é lida, já que um build para Kubernetes lê uma senha de um Secret, e não do seu shell. O exemplo mantém essa resposta em import-answers.yaml, ao lado de compose.yaml, onde a importação a procura:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.db.features.password.infra.origin: "notes-db-password"

A própria importação gravou o arquivo, na primeira vez em que foi executada com --target helm: listou o valor que não conseguiu gerar como rascunho, com a chave vazia, e parou. A resposta é o nome de um Secret, nunca a senha. A importação para Docker Compose não exige esse valor, mantém a resposta no arquivo e não a usa. O arquivo de respostas da importação descreve o arquivo, as perguntas que uma importação faz em um terminal em vez disso e o que ela faz sem nenhum dos dois.

aggrega import lista todas as flags que o comando aceita, entre elas --answers, que nomeia um arquivo de respostas mantido em outro lugar.

Entre em source:

Terminal window
cd source

Executar a importação

Terminal window
aggrega import compose.yaml --target compose

Na saída padrão, ela lista o que gravou:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Na saída de erro padrão, com <workspace> representando a pasta em que você a executou:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the compose format, with drafted paths relative to <workspace>
warn: the value of environment.POSTGRES_USER of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it empty
warn: the value of environment.POSTGRES_DB of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it empty
mapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONE
mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9
mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9
Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)

A importação executada pelo editor: o Aggregate, a Release e o Manifest em rascunho aparecem ao lado do arquivo Compose, a saída do Aggrega lista como cada serviço foi mapeado e os arquivos gravados, e uma notificação informa que a importação gerou 3 arquivos em rascunho, reconhecidos como compose.

  • As linhas warn citam cada valor que os rascunhos carregam tal como está escrito, pelo seu serviço e pela sua variável, e nunca pelo seu valor: o Compose não marca nenhum valor como credencial, e qualquer um deles poderia conter uma. Aqui, nenhum dos dois contém. As variáveis que a API lê de outro serviço não são carregadas como valores — as conexões as entregam — e as duas cujo texto é ${POSTGRES_PASSWORD} são uma referência de variável e nada mais, então nenhum aviso as cita.
  • As linhas mapped dizem no que cada serviço se transformou. api executa uma imagem própria, então é uma instância do servidor genérico da biblioteca padrão, core/compute/server. db e cache executam as imagens que as Recipes do Compose da biblioteca padrão executam para core/datastore/postgres e core/datastore/redis; cada um correspondeu a esse Component no nível alto, com 0.9, e os rascunhos fazem referência a ele.
  • A linha Pull complete é a importação buscando aquilo de que a Release rascunhada depende, como faz aggrega pull, em release.lock, para que os rascunhos sejam validados e compilados imediatamente. Com --offline, a importação não busca nada e indica o comando aggrega pull a executar.

O que a importação grava

O Aggregate, a Release e o Manifest se chamam imported/notes, a partir do name: do projeto Compose — um arquivo Compose sem name: recebe o nome do seu arquivo, compose, e o diretório que o contém, importado como diretório, o nome desse diretório, como o Compose nomeia um projeto — sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).

aggregate.yaml — uma entrada por serviço, as conexões das quais o ambiente da API se alimenta, e os valores e as senhas que o arquivo Compose define:

# Not carried, since the draft reads the services and the models alone: volumes.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/notes
version: 0.1.0
description: Draft Aggregate imported from a source in the compose format.
spec:
components:
api:
type: core/compute/server
features:
# For the compose target, the lines below declare database_password on api: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
database_password:
type: core/secret-value
values:
key: DATABASE_PASSWORD
uses:
cache:
cache:
target: cache
# The variables the source sets to what cache publishes, delivered from it under the names the source gives them.
inject:
env:
- in: "CACHE_HOST"
from: host
db:
db:
target: db
# The variables the source sets to what db publishes, delivered from it under the names the source gives them.
inject:
env:
- in: "DATABASE_HOST"
from: host
- in: "DATABASE_USER"
from: user
- in: "DATABASE_NAME"
from: database
db:
type: core/datastore/postgres
# The values of core/datastore/postgres the source sets as POSTGRES_USER, POSTGRES_DB, the variables its Compose Recipes set from them.
values:
user: "notes"
database: "notes"
features:
# For the compose target, the lines below declare password on db: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
password:
type: core/secret-value
values:
key: POSTGRES_PASSWORD
cache:
type: core/datastore/redis

Cada variável da API que cita outro serviço torna-se o bloco inject dessa conexão: o arquivo Compose definia DATABASE_HOST como db, e a conexão entrega com esse nome o host publicado pelo banco de dados, para que ele acompanhe o banco de dados em qualquer destino em vez de ser copiado. DATABASE_USER e DATABASE_NAME correspondiam ao usuário e ao banco de dados com os quais o serviço PostgreSQL é criado, então também são entregues a partir do que ele publica, e esses dois valores se tornam os values próprios do banco de dados. Cada senha torna-se um anexo core/secret-value, declarado com a chave sob a qual sua variável é lida.

release.yaml — o ambiente, a imagem e a porta da API, a versão do mecanismo de cada armazenamento de dados e a origem de cada senha:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/notes
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the compose format.
spec:
aggregate: imported/notes
manifest: imported/notes
components:
# The source also states, for the Release to carry where core/compute/server takes it:
# ports:
# - "8080:8080"
api:
infra:
image: "ghcr.io/example/notes-api:2.3.0"
port: 8080
# Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal.
published_port: 8080
features:
database_password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the value api reads as DATABASE_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
# The source states, for the Release to carry where core/datastore/postgres takes it:
# volumes:
# - "db-data:/var/lib/postgresql/data"
db:
infra:
# The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run.
engine_version: "16"
features:
password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the password of db, which the source sets as POSTGRES_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
cache:
infra:
# The tag of the image the source runs, redis:7, the engine_version of core/datastore/redis its Compose Recipes run.
engine_version: "7"

O ambiente, development, é um padrão que a importação grava porque nenhum arquivo Compose indica um; altere-o onde a Release for implantada em outro lugar. As tags de imagem se tornam as versões de mecanismo que os Components da biblioteca padrão aceitam. O port da API é a porta em que o contêiner dela escuta, e published_port a porta do host que a entrada ports dela publica, ambas 8080, como o arquivo Compose as declara; como diz o comentário, qualquer processo nesta máquina alcança a API em http://127.0.0.1:8080 e nada mais consegue, e excluir a linha a mantém apenas na rede da stack. O que nenhuma chave aceita permanece como comentário acima da sua entrada: a entrada ports da origem, que port e published_port já carregam, e o volume nomeado do banco de dados.

manifest.yaml — a Recipe do Compose de cada tipo de componente, e a realização que grava no arquivo Compose a referência de variável de uma senha tal como está escrita:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/notes
version: 0.1.0
spec:
mappings:
components:
type:
core/compute/server: compose/server
core/datastore/postgres: compose/postgres
core/datastore/redis: compose/redis
features:
type:
core/secret-value: compose/dotenv-secret

release.lock registra, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registro do que a importação gravou, que um aggrega import --sync posterior lê.

Validar e compilar

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

A Release em rascunho aberta no editor após validá-la, com a saída do Aggrega e uma notificação informando, ambas, que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista o arquivo do Docker Compose gravado e uma notificação informa que 1 arquivo foi gravado.

A validação imprime:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

e o build, com <workspace> representando a pasta em que você o executou:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 1 file written to <workspace>/dist

A linha notice é apenas informativa: a Feature de senha aceita seu origin a partir dos values do Aggregate ou da infra da Release, e o aviso informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.

O serviço api em dist/compose/docker-compose.yaml lê o ambiente que o projeto Compose lhe deu, entregue pelas conexões e pelo anexo de senha:

api:
image: ghcr.io/example/notes-api:2.3.0
environment:
CACHE_HOST: cache
DATABASE_HOST: db
DATABASE_NAME: notes
DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
DATABASE_USER: notes
ports:
- 127.0.0.1:8080:8080
[… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version]
networks:
- compose
depends_on:
- cache
- db
[… omitted: the CPU and memory the server's defaults reserve]

e o banco de dados e o cache executam as imagens que o arquivo Compose nomeava:

db:
image: postgres:16
environment:
POSTGRES_USER: notes
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: notes
[… omitted: the labels, the network and a health check running PostgreSQL's pg_isready]
cache:
image: redis:7
[… omitted: the labels, the network and a health check running redis-cli ping]

Duas diferenças em relação ao projeto com que você começou aparecem no arquivo renderizado. A porta é publicada apenas no endereço de loopback, como a Recipe do Compose do servidor genérico a publica. E o volume nomeado que o arquivo Compose montava para os dados do banco de dados não aparece em lugar nenhum: o rascunho o lista em um comentário acima da entrada do banco de dados, nenhuma chave do Component do PostgreSQL o aceita, e o serviço de banco de dados renderizado não monta nenhum volume.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do Workspace ainda não contiver uma pasta `import-compose`, chame uma vez a ferramenta `scaffold` com `example` definido como `import-compose` e sem `dir`: ela grava o exemplo em uma nova pasta `import-compose`, cuja pasta `source` contém o que esta página importa. Em seguida, chame a ferramenta `import` com `workspace_root` definido como `import-compose/source`, `source` definido como `compose.yaml` e `target` definido como `compose`: ela lê as respostas de que precisa em `import-answers.yaml`, ao lado de `compose.yaml`, grava seus rascunhos em `import-compose/source` e baixa o que eles precisam. Em seguida, chame a ferramenta `validate` com `workspace_root` definido como `import-compose/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-compose/source`, `release` definido como `release.yaml` e `write` definido como true. Diga-me quais arquivos o build gravou; eles estão em `import-compose/source/dist/`.

Abra no VS Code

Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code a pasta import-compose/source, onde a importação gravou seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as conexões entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um também é um botão no painel Commands da visualização Aggrega na barra de atividades; o Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.

Execução

ghcr.io/example/notes-api:2.3.0 representa a imagem da sua própria API. É um espaço reservado, e o Docker Compose para nele com Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Indique a imagem da sua API em infra.image de api em release.yaml. Até que sua API esteja pronta, uma imagem que responda HTTP na porta 8080 pode substituí-la. A execução abaixo usou mendhak/http-https-echo:39, que responde a cada requisição com uma descrição da requisição recebida:

api:
infra:
image: "mendhak/http-https-echo:39"
port: 8080

Faça o build de novo com a alteração. A Release não corresponde mais ao release.lock que a importação escreveu, então o build precisa de --auto-pull, que a resolve de novo; sem essa opção, o build para e cita aggrega pull. O Docker Compose preenche as duas referências ${POSTGRES_PASSWORD} a partir do seu shell, então defina a senha antes de iniciar a stack: se ela não estiver definida, o Compose avisa The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. e escreve um valor vazio no lugar dela.

Terminal window
aggrega build --release release.yaml --auto-pull
export POSTGRES_PASSWORD='a password of your own'
docker compose -p notes -f dist/compose/docker-compose.yaml up -d --wait

-p nomeia o projeto, como explica a etapa de execução de Como uma importação é executada. --wait retorna assim que o banco de dados e o cache passam nas verificações de integridade que o build lhes dá e o contêiner da API está em execução: o build não dá nenhuma verificação de integridade à API.

Teste

Consulte a API em http://127.0.0.1:8080, o endereço que published_port publica:

Terminal window
curl -sS http://127.0.0.1:8080/notes
{
"path": "/notes",
"headers": {
"host": "127.0.0.1:8080",
[… omitted: the user agent and the media types the client sent]
},
"method": "GET",
[… omitted: the rest of the request as the stand-in received it, the client's address and the container's host name]
}

O que as conexões entregam está no ambiente do serviço da API, com os nomes que sua API lê:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST
db
notes
notes
cache

Pare a stack com:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml down

No Kubernetes

O mesmo projeto é importado para o Kubernetes com --target helm, e a importação lê o nome do Secret, notes-db-password, no arquivo de respostas acima. Os rascunhos para o Docker Compose já estão em source, então gere estes em uma pasta própria, indique a imagem da API no release.yaml dela como para o Docker Compose e faça o build a partir dela:

Terminal window
aggrega import compose.yaml --target helm --output-dir helm
cd helm
aggrega build --release release.yaml --auto-pull

O build grava manifestos simples do Kubernetes em dist/helm/ na raiz do workspace, source, que a partir de helm é ../dist/helm/. Crie o Secret notes-db-password no namespace em que você aplica, com a senha sob a chave de dados value, e aplique a pasta como explica a etapa de execução de Como uma importação é executada. O Service da API é api-default: encaminhe uma porta local para ele e deixe o comando em execução:

Terminal window
kubectl port-forward -n <namespace> svc/api-default 8080:8080

Em outro terminal, a requisição acima alcança a API no mesmo endereço, sem alterações, e a imagem substituta responde da mesma forma, "host": "127.0.0.1:8080". As conexões entregam os nomes dos Services: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST imprime db-default, notes, notes e cache-default. No Kubernetes, a API ainda não recebe a senha do seu banco de dados: o Secret notes-db-password chega apenas ao banco de dados, então DATABASE_PASSWORD não é definida no contêiner api.

Quando o arquivo Compose muda

Mantenha .aggrega-import.json ao lado dos rascunhos e, depois que o arquivo Compose mudar, execute:

Terminal window
aggrega import compose.yaml --sync

Ele altera apenas o que a importação escreveu e lê o mesmo arquivo de respostas. Uma parte que a origem não alterou permanece como está no disco, editada ou não; onde a origem alterou uma parte que você editou, ele para, cita a parte e não escreve nada, para que você concilie manualmente. aggrega import descreve por completo as regras e cada flag.