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

Importar um projeto Compose

Este guia passo a passo importa um pequeno projeto Compose — uma API, a base de dados PostgreSQL onde guarda as suas notas e uma cache Redis — e compila o resultado para Docker Compose. A importação gera como rascunho cada ficheiro que o build lê, transportando o que o ficheiro Compose declara: as ligações da API à base de dados e à cache, o utilizador e o nome da base de dados, a palavra-passe como referência a variável e a tag de cada imagem. Cada ficheiro e cada bloco de saída abaixo provêm de uma execução real; o projeto e cada etapa do guia estão no exemplo import-compose, onde um script de verificação volta a executar a importação, compara o que ela escreve, o que imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.

Gerar o exemplo

É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.

Escreva o exemplo numa nova pasta com o nome dele:

Terminal window
aggrega scaffold --example import-compose

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, 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, a mostrar o seu ficheiro Compose: a API de um serviço de notas, a respetiva base de dados PostgreSQL e a respetiva 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, pelo que a importação escreve aí os seus rascunhos:

# 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, pelo que a importação lê o catálogo da biblioteca padrão a partir do registo do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que é identificado pelo seu digest no ficheiro de registo que a importação escreve junto aos seus rascunhos. Um espaço de trabalho que indica as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS ou em workspace.catalog_dirs — importa antes face a essas.

O ficheiro de respostas

Uma build para Docker Compose não precisa de nada que o ficheiro Compose não declare, pelo que esta importação não pergunta nada. Uma build do mesmo projeto para Kubernetes, com --target helm, precisa de um valor que nenhum ficheiro Compose contém: o nome do Secret do Kubernetes a partir do qual a palavra-passe da base de dados é lida, uma vez que uma build para Kubernetes lê uma palavra-passe a partir de um Secret e não da shell do utilizador. O exemplo guarda essa resposta em import-answers.yaml, junto a 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 escreveu o ficheiro, da primeira vez que foi executada com --target helm: listou o valor que não conseguia gerar como rascunho, com a chave vazia, e parou. A resposta é o nome de um Secret, nunca a palavra-passe. A importação para Docker Compose não exige esse valor, mantém a resposta no ficheiro e não a utiliza. O ficheiro de respostas da importação descreve o ficheiro, as perguntas que uma importação faz antes num terminal e o que faz sem nenhum dos dois.

aggrega import lista todas as flags que o comando aceita, entre elas --answers, que indica um ficheiro de respostas guardado noutro local.

Entre em source:

Terminal window
cd source

Executar a importação

Terminal window
aggrega import compose.yaml --target compose

Na saída padrão, lista o que escreveu:

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

Na saída de erro padrão, com <workspace> a representar a pasta em que 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 a partir do editor: o Aggregate, a Release e o Manifest em rascunho aparecem ao lado do ficheiro Compose, a saída do Aggrega lista como cada serviço foi mapeado e os ficheiros escritos, e uma notificação indica que a importação gerou 3 ficheiros em rascunho, reconhecidos como compose.

  • As linhas warn nomeiam cada valor que os rascunhos transportam 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 de todo transportadas como valores — as ligações entregam-nas — e as duas cujo texto é ${POSTGRES_PASSWORD} são uma referência de variável e nada mais, pelo que nenhum aviso as nomeia.
  • As linhas mapped indicam em que se tornou cada serviço. api executa uma imagem própria, pelo que é 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-lhe referência.
  • A linha Pull complete é a importação a obter aquilo de que a Release rascunhada depende, como faz aggrega pull, para release.lock, para que os rascunhos sejam validados e compilados de imediato. Com --offline, a importação não obtém nada e indica o comando aggrega pull a executar.

O que a importação escreve

O Aggregate, a Release e o Manifest chamam-se imported/notes, a partir do name: do projeto Compose — um ficheiro Compose sem name: recebe o nome do seu ficheiro, compose, e o diretório que o contém, importado como diretório, o nome desse diretório, tal como o Compose nomeia um projeto — no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definições).

aggregate.yaml — uma entrada por serviço, as ligações de onde o ambiente da API obtém os seus valores, e os valores e as palavras-passe que o ficheiro 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 nomeia outro serviço torna-se o bloco inject dessa ligação: o ficheiro Compose definia DATABASE_HOST como db, e a ligação entrega com esse nome o host publicado pela base de dados, para que este acompanhe a base de dados em qualquer destino em vez de ser copiado. DATABASE_USER e DATABASE_NAME correspondiam ao utilizador e à base de dados com que o serviço PostgreSQL é criado, pelo que também são entregues a partir do que este publica, e esses dois valores tornam-se os values próprios da base de dados. Cada palavra-passe torna-se um anexo core/secret-value, declarado com a chave sob a qual a sua variável é lida.

release.yaml — o ambiente, a imagem e a porta da API, a versão do motor de cada armazenamento de dados e a origem de cada palavra-passe:

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 valor predefinido que a importação escreve porque nenhum ficheiro Compose indica um; altere-o onde a Release for implementada noutro local. As tags de imagem tornam-se as versões de motor que os Components da biblioteca padrão aceitam. O port da API é a porta em que o respetivo contentor está à escuta, e published_port a porta do anfitrião que a respetiva entrada ports publica, ambas 8080, tal como o ficheiro Compose as indica; como diz o respetivo comentário, qualquer processo nesta máquina chega à API em http://127.0.0.1:8080 e nada mais consegue fazê-lo, e eliminar a linha mantém-na apenas na rede da stack. O que nenhuma chave aceita fica como comentário acima da respetiva entrada: a entrada ports da origem, que port e published_port já transportam, e o volume com nome da base de dados.

manifest.yaml — a Recipe do Compose de cada tipo de componente, e a realização que escreve no ficheiro Compose a referência de variável de uma palavra-passe 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 regista, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registo do que a importação escreveu, 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 depois de validada, com a saída do Aggrega e uma notificação a indicarem, ambas, que não foram encontrados problemas.

A compilação da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista o ficheiro do Docker Compose escrito e uma notificação indica que foi escrito 1 ficheiro.

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> a representar a pasta onde 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 é meramente informativa: a Feature de palavra-passe aceita o seu origin a partir dos values do Aggregate ou da infra da Release, e o aviso comunica que uma folha está declarada em ambos. Não altera nenhum veredicto.

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

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 a base de dados e a cache executam as imagens que o ficheiro Compose indicava:

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 inicial veem-se no ficheiro renderizado. A porta é publicada apenas no endereço de loopback, tal como a Recipe do Compose do servidor genérico a publica. E o volume com nome que o ficheiro Compose montava para os dados da base de dados não aparece em lado nenhum: o rascunho lista-o num comentário acima da entrada da base de dados, nenhuma chave do Component do PostgreSQL o aceita, e o serviço de base 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 nele este prompt.

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`: esta escreve o exemplo numa nova pasta `import-compose`, cuja pasta `source` contém o que esta página importa. Depois, chame a ferramenta `import` com `workspace_root` definido como `import-compose/source`, `source` definido como `compose.yaml` e `target` definido como `compose`: esta lê as respostas de que precisa em `import-answers.yaml`, ao lado de `compose.yaml`, escreve os seus rascunhos em `import-compose/source` e obtém aquilo de que estes precisam. Depois, 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. Indique-me que ficheiros a compilação escreveu; estão em `import-compose/source/dist/`.

Abrir 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 escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as ligaçõ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 vista Aggrega na barra de atividade; o Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code trata do resto.

Execução

ghcr.io/example/notes-api:2.3.0 representa a imagem da sua própria API. É um marcador de posição, 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. Enquanto a sua API não estiver pronta, uma imagem que responda por HTTP na porta 8080 pode substituí-la. A execução abaixo utilizou mendhak/http-https-echo:39, que responde a cada pedido com uma descrição do pedido recebido:

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

Volte a executar o build com a alteração. A Release já não corresponde ao release.lock que a importação escreveu, pelo que o build precisa de --auto-pull, que a resolve novamente; sem essa opção, o build para e indica aggrega pull. O Docker Compose preenche as duas referências ${POSTGRES_PASSWORD} a partir da shell, pelo que deve definir a palavra-passe antes de iniciar a stack: se 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 seu lugar.

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 dá nome ao projeto, como explica o passo de execução de Como decorre uma importação. --wait retorna assim que a base de dados e a cache passam as verificações de estado que o build lhes atribui e o contentor da API está em execução: o build não atribui nenhuma verificação de estado à API.

Testar

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 ligações entregam está no ambiente do serviço da API, com os nomes que a 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 importa-se para o Kubernetes com --target helm, e a importação lê o nome do Secret, notes-db-password, do ficheiro de respostas acima. Os rascunhos para o Docker Compose já estão em source, pelo que estes devem ser gerados numa pasta própria; indique a imagem da API no respetivo release.yaml, tal como para o Docker Compose, e compile a partir dessa pasta:

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

A compilação escreve manifestos simples do Kubernetes em dist/helm/ na raiz do workspace, source, o que a partir de helm é ../dist/helm/. Crie o Secret notes-db-password no namespace onde aplica, com a palavra-passe sob a chave de dados value, e aplique a pasta como explica o passo de execução de Como decorre uma importação. O Service da API é api-default: reencaminhe uma porta local para ele e deixe o comando em execução:

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

Noutro terminal, o pedido acima chega à API no mesmo endereço, sem alterações, e a imagem substituta responde da mesma forma, "host": "127.0.0.1:8080". As ligaçõ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 palavra-passe da sua base de dados: o Secret notes-db-password chega apenas à base de dados, pelo que DATABASE_PASSWORD não está definida no contentor api.

Quando o ficheiro Compose muda

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

Terminal window
aggrega import compose.yaml --sync

Altera apenas o que a importação escreveu e lê o mesmo ficheiro de respostas. Uma parte que a origem não alterou fica como está no disco, editada ou não; onde a origem alterou uma parte que foi editada, para, nomeia a parte e não escreve nada, para que a reconciliação seja feita à mão. aggrega import descreve na íntegra as regras e cada flag.