Importowanie projektu Compose
Ten przewodnik krok po kroku importuje mały projekt Compose — API, bazę danych PostgreSQL, w której API przechowuje swoje notatki, oraz pamięć podręczną Redis — i buduje wynik dla Docker Compose. Import tworzy szkic każdego pliku, który odczytuje build, przenosząc to, co określa plik Compose: połączenia API z bazą danych i pamięcią podręczną, użytkownika i nazwę bazy danych, hasło jako odwołanie do zmiennej oraz tag każdego obrazu. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; projekt i każdy etap przewodnika znajdują się w przykładzie import-compose, gdzie skrypt kontrolny ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.
Generowanie przykładu
Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example import-composeNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:
cd import-compose
Projekt
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:Obok niego plik .aggrega-config.yaml czyni folder obszarem roboczym, dzięki czemu import zapisuje tam swoje szkice:
# 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.aiImport porównuje każdą usługę z encjami Components z katalogu obszaru roboczego, a --target tworzy szkic encji Manifest na podstawie encji Recipes z tego katalogu. Obszar roboczy nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, pobraną, zweryfikowaną i przechowywaną w pamięci podręcznej treści obszaru roboczego przez pierwszy import oraz wskazaną przez jej skrót w zapisie, który import umieszcza obok swoich szkiców. Obszar roboczy, który wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub w workspace.catalog_dirs — importuje zamiast tego względem nich.
Plik odpowiedzi
Kompilacja dla Docker Compose nie potrzebuje niczego, czego nie podaje plik Compose, więc ten import o nic nie pyta. Kompilacja tego samego projektu dla Kubernetes, z --target helm, potrzebuje jednej wartości, której nie zawiera żaden plik Compose: nazwy obiektu Secret Kubernetes, z którego odczytywane jest hasło bazy danych, ponieważ kompilacja dla Kubernetes odczytuje hasło z obiektu Secret, a nie z powłoki użytkownika. Przykład przechowuje tę odpowiedź w import-answers.yaml, obok compose.yaml, gdzie import jej szuka:
# 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"Import sam zapisał ten plik, gdy po raz pierwszy uruchomiono go z --target helm: wymienił wartość, której nie mógł naszkicować, z pustym kluczem, i zatrzymał się. Odpowiedzią jest nazwa obiektu Secret, nigdy hasło. Import dla Docker Compose nie wymaga takiej wartości, zachowuje odpowiedź w pliku i jej nie używa. Plik odpowiedzi importu opisuje ten plik, pytania, które import zadaje zamiast tego w terminalu, oraz to, co robi bez żadnego z nich.
aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.
Należy przejść do source:
cd sourceUruchomienie importu
aggrega import compose.yaml --target composeNa standardowym wyjściu wymienia to, co zapisał:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:
[… 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 emptywarn: 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 emptymapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONEmapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)
- Wiersze
warnwymieniają każdą wartość, którą szkice przenoszą w zapisanej postaci, przez jej usługę i zmienną, a nigdy przez samą wartość: Compose nie oznacza żadnej wartości jako poświadczenia, a każda z nich mogłaby je zawierać. Tutaj żadna z dwóch nie zawiera. Zmienne, które API odczytuje z innej usługi, w ogóle nie są przenoszone jako wartości — dostarczają je połączenia — a dwie o treści${POSTGRES_PASSWORD}są odwołaniem do zmiennej i niczym więcej, więc żadne ostrzeżenie ich nie wymienia. - Wiersze
mappedmówią, czym stała się każda usługa.apiuruchamia własny obraz, więc jest instancją generycznego serwera biblioteki standardowej,core/compute/server.dbicacheuruchamiają te obrazy, które encje Recipes dla Compose z biblioteki standardowej uruchamiają dlacore/datastore/postgresicore/datastore/redis; każda z tych usług została dopasowana do tej encji Component na wysokim poziomie, z wynikiem 0.9, a szkice się do niej odwołują. - Wiersz
Pull completeoznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi toaggrega pull, dorelease.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z--offlineimport niczego nie pobiera i podaje polecenieaggrega pull, które należy uruchomić.
Co zapisuje import
Encje Aggregate, Release i Manifest otrzymują nazwę imported/notes od name: projektu Compose — plik Compose bez name: otrzymuje nazwę od swojego pliku, compose, a katalog, który go zawiera, zaimportowany jako katalog, od tego katalogu, tak jak Compose nazywa projekt — w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).
aggregate.yaml — jeden wpis na usługę, połączenia, z których czerpie środowisko API, oraz wartości i hasła ustawiane przez plik Compose:
# Not carried, since the draft reads the services and the models alone: volumes.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: 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/redisKażda zmienna API, która wskazuje inną usługę, staje się blokiem inject tego połączenia: plik Compose ustawiał DATABASE_HOST na db, a połączenie dostarcza pod tą nazwą opublikowany przez bazę danych host, dzięki czemu podąża on za bazą danych na dowolnym celu, zamiast być kopiowanym. DATABASE_USER i DATABASE_NAME odpowiadały użytkownikowi i bazie danych, z którymi tworzona jest usługa PostgreSQL, więc one również są dostarczane na podstawie tego, co ona publikuje, a te dwie wartości stają się własnymi values bazy danych. Każde hasło staje się dołączeniem core/secret-value, zadeklarowanym z kluczem, pod którym odczytywana jest jego zmienna.
release.yaml — środowisko, obraz i port API, wersja silnika każdego magazynu danych oraz źródło każdego hasła:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: 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"Środowisko, development, to wartość domyślna, którą import zapisuje, ponieważ żaden plik Compose go nie wskazuje; należy ją zmienić tam, gdzie encja Release jest wdrażana gdzie indziej. Tagi obrazów stają się wersjami silnika, które przyjmują encje Components z biblioteki standardowej. port API to port, na którym nasłuchuje jego kontener, a published_port to port hosta publikowany przez jego wpis ports, oba równe 8080, tak jak podaje je plik Compose; jak mówi jego komentarz, każdy proces na tej maszynie dociera do API pod adresem http://127.0.0.1:8080 i nic innego nie może tego zrobić, a usunięcie tego wiersza pozostawia API wyłącznie w sieci stosu. To, czego nie przyjmuje żaden klucz, pozostaje komentarzem nad swoim wpisem: wpis ports ze źródła, który port i published_port już przenoszą, oraz nazwany wolumen bazy danych.
manifest.yaml — encja Recipe dla Compose każdego typu komponentu oraz realizacja, która zapisuje w pliku Compose odwołanie do zmiennej hasła w zapisanej postaci:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/notes version: 0.1.0spec: 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-secretrelease.lock rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.
Walidacja i kompilacja
aggrega validate --release release.yamlaggrega build --release release.yaml

Walidacja wypisuje:
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)oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:
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>/distWiersz notice ma charakter wyłącznie informacyjny: encja Feature dla hasła przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat informuje, że jeden liść jest zadeklarowany w obu. Nie zmienia on żadnego werdyktu.
Usługa api w dist/compose/docker-compose.yaml odczytuje środowisko, które nadał jej projekt Compose, dostarczane przez połączenia i dołączenie hasła:
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]a baza danych i pamięć podręczna uruchamiają obrazy wskazane w pliku 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]Dwie różnice względem projektu wyjściowego są widoczne w wygenerowanym pliku. Port jest publikowany wyłącznie na adresie pętli zwrotnej, tak jak publikuje go encja Recipe dla Compose generycznego serwera. A nazwany wolumin, który plik Compose montował na dane bazy danych, nigdzie się nie pojawia: szkic wymienia go w komentarzu nad wpisem bazy danych, żaden klucz encji Component PostgreSQL go nie przyjmuje, a wygenerowana usługa bazy danych nie montuje żadnego woluminu.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-compose`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-compose` i bez `dir`: zapisuje ono przykład w nowym folderze `import-compose`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-compose/source`, `source` ustawionym na `compose.yaml` i `target` ustawionym na `compose`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` obok `compose.yaml`, zapisuje wersje robocze w `import-compose/source` i pobiera to, czego one potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-compose/source` i `release` ustawionym na `release.yaml` oraz narzędzie `build` z `workspace_root` ustawionym na `import-compose/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj, które pliki zapisała kompilacja; znajdują się w `import-compose/source/dist/`.Otwieranie w VS Code
Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-compose/source, w którym import zapisał wersje robocze. Folder zawiera jedną encję Release, wersję roboczą release.yaml, więc edytor sam ją wybiera i podczas edycji sprawdza wersje robocze względem tej encji Release, oznaczając znalezione problemy w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ folderu. Resztę omawia Używanie Aggrega w Visual Studio Code.
Uruchomienie
ghcr.io/example/notes-api:2.3.0 oznacza obraz własnego API. Jest to symbol zastępczy, na którym Docker Compose zatrzymuje się z komunikatem Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Obraz swojego API należy podać w infra.image dla api w release.yaml. Dopóki API nie jest gotowe, może je zastąpić obraz odpowiadający przez HTTP na porcie 8080. W poniższym uruchomieniu użyto mendhak/http-https-echo:39, który na każde żądanie odpowiada opisem otrzymanego żądania:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Należy ponownie wykonać build ze zmianą. Encja Release nie odpowiada już plikowi release.lock zapisanemu przez import, dlatego build wymaga --auto-pull, które rozwiązuje ją ponownie; bez tej opcji build zatrzymuje się i wskazuje aggrega pull. Docker Compose wypełnia oba odwołania ${POSTGRES_PASSWORD} z powłoki, dlatego hasło trzeba ustawić przed uruchomieniem stosu: jeśli nie zostanie ustawione, Compose ostrzega The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. i wpisuje w jego miejsce pustą wartość.
aggrega build --release release.yaml --auto-pullexport POSTGRES_PASSWORD='a password of your own'docker compose -p notes -f dist/compose/docker-compose.yaml up -d --wait-p nadaje nazwę projektowi, jak wyjaśnia krok uruchamiania w Jak przebiega import. --wait zwraca sterowanie, gdy baza danych i pamięć podręczna przejdą kontrole stanu, które nadaje im kompilacja, a kontener API jest uruchomiony: kompilacja nie nadaje API żadnej kontroli stanu.
Testowanie
Należy odpytać API pod adresem http://127.0.0.1:8080, który publikuje published_port:
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]}To, co dostarczają połączenia, znajduje się w środowisku usługi API, pod nazwami, które odczytuje API:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheStack zatrzymuje się poleceniem:
docker compose -p notes -f dist/compose/docker-compose.yaml downNa Kubernetes
Ten sam projekt importuje się dla Kubernetes z --target helm, a import odczytuje nazwę obiektu Secret, notes-db-password, z powyższego pliku odpowiedzi. Wersje robocze dla Docker Compose znajdują się już w source, więc te należy utworzyć w osobnym folderze, podać obraz API w jego release.yaml tak jak dla Docker Compose i skompilować z tego folderu:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullKompilacja zapisuje zwykłe manifesty Kubernetes w dist/helm/ w katalogu głównym obszaru roboczego, source, czyli z perspektywy helm w ../dist/helm/. Należy utworzyć Secret notes-db-password w przestrzeni nazw, do której się stosuje, z hasłem pod kluczem danych value, i zastosować folder, jak wyjaśnia krok uruchamiania w Jak przebiega import. Service API to api-default: należy przekierować do niego lokalny port i pozostawić polecenie uruchomione:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Z innego terminala powyższe żądanie dociera bez zmian do API pod tym samym adresem, a obraz zastępczy odpowiada w ten sam sposób, "host": "127.0.0.1:8080". Połączenia dostarczają nazwy obiektów Service: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST wypisuje db-default, notes, notes i cache-default. W Kubernetes API nie otrzymuje jeszcze hasła do swojej bazy danych: Secret notes-db-password trafia tylko do bazy danych, więc DATABASE_PASSWORD nie jest ustawiona w kontenerze api.
Gdy plik Compose się zmienia
Plik .aggrega-import.json należy przechowywać obok szkiców, a po zmianie pliku Compose uruchomić:
aggrega import compose.yaml --syncPolecenie zmienia tylko to, co zapisał import, i odczytuje ten sam plik odpowiedzi. Część, której źródło nie zmieniło, pozostaje taka, jaka jest na dysku, edytowana czy nie; tam, gdzie źródło zmieniło część edytowaną przez użytkownika, polecenie zatrzymuje się, wskazuje tę część i niczego nie zapisuje, aby można było ją uzgodnić ręcznie. aggrega import opisuje w całości zasady i każdą flagę.