Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Importer un projet Compose

Ce guide pas à pas importe un petit projet Compose — une API, la base de données PostgreSQL dans laquelle elle conserve ses notes et un cache Redis — et construit le résultat pour Docker Compose. L’importation ébauche chaque fichier que lit le build, en reprenant ce qu’énonce le fichier Compose : les connexions de l’API à la base de données et au cache, l’utilisateur et le nom de la base de données, le mot de passe sous forme de référence de variable, et le tag de chaque image. Chaque fichier et chaque bloc de sortie ci-dessous proviennent d’une exécution réelle ; le projet et chaque étape du guide se trouvent dans l’exemple import-compose, où un script de vérification relance l’importation, compare ce qu’elle écrit, ce qu’elle affiche et les blocs que cite cette page avec les fichiers qui y sont conservés, puis valide et construit ce que l’importation a écrit.

Générer l’exemple

Vous pouvez exécuter cette importation avec les commandes de cette page, ou la faire exécuter par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example import-compose

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier ; la suivante, ci-dessous, vous place dans le dossier source du nouveau dossier, qui contient ce que cette page importe et où s’exécute l’import :

Terminal window
cd import-compose

Le dossier source de l’exemple généré, ouvert dans Visual Studio Code, montrant son fichier Compose : l’API d’un service de notes, sa base de données PostgreSQL et son cache Redis.

Le projet

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:

À côté, un fichier .aggrega-config.yaml fait du dossier un espace de travail, si bien que l’importation y écrit ses ébauches :

# 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

L’importation compare chaque service aux Components du catalogue de l’espace de travail, et --target ébauche un Manifest à partir des Recipes du catalogue. L’espace de travail ne nomme aucun dossier de catalogue ; l’importation lit donc le catalogue de la bibliothèque standard depuis le registre dont elle récupère son importeur : un instantané signé du catalogue publié, récupéré, vérifié et conservé dans le cache de contenu de l’espace de travail par la première importation, et nommé par son condensé dans l’enregistrement que l’importation écrit à côté de ses brouillons. Un espace de travail qui nomme ses propres dossiers de catalogue — dans AGGREGA_CATALOG_DIRS, ou sous workspace.catalog_dirs — importe plutôt par rapport à ceux-ci.

Le fichier de réponses

Un build pour Docker Compose n’a besoin de rien que le fichier Compose n’indique pas ; cette importation ne demande donc rien. Un build du même projet pour Kubernetes, avec --target helm, a besoin d’une valeur qu’aucun fichier Compose ne contient : le nom du Secret Kubernetes dans lequel le mot de passe de la base de données est lu, puisqu’un build Kubernetes lit un mot de passe dans un Secret plutôt que dans votre shell. L’exemple conserve cette réponse dans import-answers.yaml, à côté de compose.yaml, là où l’importation la cherche :

# 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"

L’importation a écrit le fichier elle-même, la première fois qu’elle a été exécutée avec --target helm : elle a listé la valeur qu’elle ne pouvait pas ébaucher, avec sa clé vide, et s’est arrêtée. La réponse est le nom d’un Secret, jamais le mot de passe. L’importation pour Docker Compose ne doit aucune valeur de ce type, conserve la réponse dans le fichier et ne l’utilise pas. Le fichier de réponses de l’importation décrit le fichier, les questions qu’une importation pose à la place dans un terminal, et ce qu’elle fait en l’absence des deux.

aggrega import liste toutes les options que prend la commande, dont --answers, qui nomme un fichier de réponses conservé ailleurs.

Placez-vous dans source :

Terminal window
cd source

Lancer l’importation

Terminal window
aggrega import compose.yaml --target compose

Sur la sortie standard, elle liste ce qu’elle a écrit :

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

Sur la sortie d’erreur standard, où <workspace> désigne le dossier dans lequel vous l’avez lancée :

[… 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)

L’importation lancée depuis l’éditeur : l’Aggregate, la Release et le Manifest rédigés apparaissent à côté du fichier Compose, la sortie d’Aggrega liste la correspondance établie pour chaque service et les fichiers écrits, et une notification indique que l’importation a rédigé 3 fichiers, reconnus comme compose.

  • Les lignes warn nomment chaque valeur que les brouillons reprennent telle qu’elle est écrite, par son service et sa variable et jamais par sa valeur : Compose ne marque aucune valeur comme identifiant, et n’importe laquelle pourrait en contenir un. Ici, aucune des deux n’en contient. Les variables que l’API lit depuis un autre service ne sont pas du tout reprises comme valeurs — les connexions les fournissent — et les deux qui valent ${POSTGRES_PASSWORD} sont une référence de variable et rien d’autre ; aucun avertissement ne les nomme donc.
  • Les lignes mapped indiquent ce que chaque service est devenu. api exécute une image qui lui est propre ; c’est donc une instance du serveur générique de la bibliothèque standard, core/compute/server. db et cache exécutent les images que les Recipes Compose de la bibliothèque standard exécutent pour core/datastore/postgres et core/datastore/redis ; chacun a correspondu à ce Component dans le niveau haut, à 0.9, et les brouillons y font référence.
  • La ligne Pull complete correspond à l’import qui récupère ce dont dépend la Release rédigée, comme le fait aggrega pull, dans release.lock, de sorte que les brouillons se valident et se construisent immédiatement. Avec --offline, l’import ne récupère rien et indique la commande aggrega pull à exécuter.

Ce qu’elle écrit

L’Aggregate, la Release et le Manifest sont nommés imported/notes, d’après le name: du projet Compose — un fichier Compose sans name: est nommé d’après son fichier, compose, et le répertoire qui le contient, importé en tant que répertoire, d’après ce répertoire, comme Compose nomme un projet —, sous le namespace que fixe le paramètre target_namespace de l’importeur, imported sauf si vous en fixez un autre (Paramètres).

aggregate.yaml — une entrée par service, les connexions dont s’alimente l’environnement de l’API, ainsi que les valeurs et les mots de passe que définit le fichier Compose :

# 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

Chaque variable de l’API qui nomme un autre service devient le bloc inject de cette connexion : le fichier Compose définissait DATABASE_HOST à db, et la connexion fournit sous ce nom le host publié par la base de données, si bien qu’il suit la base de données sur n’importe quelle cible au lieu d’être copié. DATABASE_USER et DATABASE_NAME correspondaient à l’utilisateur et à la base de données avec lesquels le service PostgreSQL est créé ; ils sont donc eux aussi fournis à partir de ce qu’il publie, et ces deux valeurs deviennent les values propres de la base de données. Chaque mot de passe devient un attachement core/secret-value, déclaré avec la clé sous laquelle sa variable est lue.

release.yaml — l’environnement, l’image et le port de l’API, la version du moteur de chaque magasin de données, et la provenance de chaque mot de 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"

L’environnement, development, est une valeur par défaut que l’importation écrit parce qu’aucun fichier Compose n’en nomme ; modifiez-la là où la Release est déployée ailleurs. Les tags d’image deviennent les versions de moteur qu’acceptent les Components de la bibliothèque standard. Le port de l’API est le port sur lequel son conteneur écoute, et published_port le port de l’hôte que publie son entrée ports, tous deux à 8080 comme les indique le fichier Compose ; comme le dit son commentaire, tout processus de cette machine atteint l’API à http://127.0.0.1:8080 et rien d’autre ne le peut, et supprimer la ligne la garde sur le seul réseau de la stack. Ce qu’aucune clé n’accepte reste un commentaire au-dessus de son entrée : l’entrée ports de la source, que port et published_port portent déjà, et le volume nommé de la base de données.

manifest.yaml — la Recipe Compose de chaque type de composant, et la réalisation qui écrit telle quelle dans le fichier Compose la référence de variable d’un mot de passe :

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 enregistre, par digest, les entités du catalogue vers lesquelles la Release a été résolue, et .aggrega-import.json est l’enregistrement de ce que l’importation a écrit, que lit un aggrega import --sync ultérieur.

Valider et compiler

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

La Release rédigée par l’importation, ouverte dans l’éditeur après sa validation, avec la sortie d’Aggrega et une notification qui indiquent toutes deux qu’aucun problème n’a été trouvé.

Le build de la Release rédigée : un dossier dist apparaît dans l’Explorateur, la sortie d’Aggrega liste le fichier Docker Compose écrit et une notification indique qu’1 fichier a été écrit.

La validation affiche :

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)

et le build, où <workspace> désigne le dossier dans lequel vous l’avez exécuté :

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

La ligne notice est purement informative : la Feature du mot de passe accepte son origin depuis les values de l’Aggregate ou depuis infra de la Release, et la notice signale qu’une feuille est déclarée dans les deux. Elle ne change aucun verdict.

Le service api dans dist/compose/docker-compose.yaml lit l’environnement que le projet Compose lui donnait, fourni par les connexions et l’attachement du mot de 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]

et la base de données et le cache exécutent les images que nommait le fichier Compose :

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]

Deux différences par rapport au projet de départ apparaissent dans le fichier rendu. Le port est publié sur la seule adresse de bouclage, comme le publie la Recipe Compose du serveur générique. Et le volume nommé que le fichier Compose montait pour les données de la base n’apparaît nulle part : l’ébauche le liste dans un commentaire au-dessus de l’entrée de la base de données, aucune clé du Component PostgreSQL ne l’accepte, et le service de base de données rendu ne monte aucun volume.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier du Workspace ne contient pas encore de dossier `import-compose`, appelez une fois l’outil `scaffold` avec `example` défini sur `import-compose` et sans `dir` : il écrit l’exemple dans un nouveau dossier `import-compose`, dont le dossier `source` contient ce que cette page importe. Appelez ensuite l’outil `import` avec `workspace_root` défini sur `import-compose/source`, `source` défini sur `compose.yaml` et `target` défini sur `compose` : il lit les réponses dont il a besoin dans `import-answers.yaml`, à côté de `compose.yaml`, écrit ses brouillons dans `import-compose/source` et récupère ce dont ils ont besoin. Appelez ensuite l’outil `validate` avec `workspace_root` défini sur `import-compose/source` et `release` défini sur `release.yaml`, puis l’outil `build` avec `workspace_root` défini sur `import-compose/source`, `release` défini sur `release.yaml` et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `import-compose/source/dist/`.

L’ouvrir dans VS Code

Une fois l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le dossier import-compose/source, où l’importation a écrit ses brouillons. Le dossier contient une seule Release, le release.yaml rédigé, donc l’éditeur la sélectionne pour vous et vérifie les brouillons par rapport à cette Release à mesure que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du dossier. Utiliser Aggrega dans Visual Studio Code couvre le reste.

Exécution

ghcr.io/example/notes-api:2.3.0 représente l’image de votre propre API. C’est un espace réservé, et Docker Compose s’arrête dessus avec Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Indiquez l’image de votre API dans infra.image de api dans release.yaml. En attendant que votre API soit prête, une image qui répond en HTTP sur le port 8080 peut la remplacer. L’exécution ci-dessous a utilisé mendhak/http-https-echo:39, qui répond à chaque requête par une description de la requête reçue :

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

Relancez le build avec la modification. La Release ne correspond plus au release.lock que l’importation a écrit, donc le build a besoin de --auto-pull, qui la résout à nouveau ; sans cette option, le build s’arrête et nomme aggrega pull. Docker Compose renseigne les deux références ${POSTGRES_PASSWORD} à partir de votre shell, donc définissez le mot de passe avant de démarrer la pile : s’il n’est pas défini, Compose avertit The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. et écrit une valeur vide à sa place.

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 nomme le projet, comme l’explique l’étape d’exécution de Déroulement d’une importation. --wait rend la main dès que la base de données et le cache passent les contrôles de santé que le build leur attribue et que le conteneur de l’API est en cours d’exécution : le build n’attribue aucun contrôle de santé à l’API.

Tester

Interrogez l’API à http://127.0.0.1:8080, l’adresse que publie published_port :

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]
}

Ce que livrent les connexions se trouve dans l’environnement du service de l’API, sous les noms que lit votre API :

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

Arrêtez la pile avec :

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

Sur Kubernetes

Le même projet s’importe pour Kubernetes avec --target helm, et l’importation lit le nom du Secret, notes-db-password, dans le fichier de réponses ci-dessus. Les brouillons pour Docker Compose se trouvent déjà dans source, donc rédigez ceux-ci dans un dossier à part, nommez l’image de l’API dans son release.yaml comme pour Docker Compose, et lancez le build depuis ce dossier :

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

Le build écrit de simples manifestes Kubernetes sous dist/helm/ à la racine du workspace, source, ce qui depuis helm correspond à ../dist/helm/. Créez le Secret notes-db-password dans le namespace où vous appliquez, avec le mot de passe sous la clé de données value, et appliquez le dossier comme l’explique l’étape d’exécution de Déroulement d’une importation. Le Service de l’API est api-default : redirigez un port local vers lui et laissez la commande s’exécuter :

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

Depuis un autre terminal, la requête ci-dessus atteint l’API à la même adresse, inchangée, et l’image de remplacement répond de la même façon, "host": "127.0.0.1:8080". Les connexions fournissent les noms des Services : kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST affiche db-default, notes, notes et cache-default. Sur Kubernetes, l’API ne reçoit pas encore le mot de passe de sa base de données : le Secret notes-db-password n’atteint que la base de données, donc DATABASE_PASSWORD n’est pas défini dans le conteneur api.

Quand le fichier Compose change

Conservez .aggrega-import.json à côté des ébauches et, après une modification du fichier Compose, exécutez :

Terminal window
aggrega import compose.yaml --sync

La commande ne modifie que ce que l’importation a écrit, et lit le même fichier de réponses. Une partie que la source n’a pas touchée reste telle qu’elle est sur le disque, modifiée ou non ; là où la source a changé une partie que vous avez modifiée, elle s’arrête, nomme la partie et n’écrit rien, pour que vous la réconciliiez à la main. aggrega import décrit en détail les règles et chaque option.