Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

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:

Terminal window
aggrega scaffold --example import-compose

Nastę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:

Terminal window
cd import-compose

Folder source wygenerowanego przykładu otwarty w Visual Studio Code, z widocznym plikiem Compose: API usługi notatek, jej bazą danych PostgreSQL i pamięcią podręczną Redis.

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.ai

Import 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:

Terminal window
cd source

Uruchomienie importu

Terminal window
aggrega import compose.yaml --target compose

Na standardowym wyjściu wymienia to, co zapisał:

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

Na 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 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)

Import uruchomiony z edytora: wersje robocze encji Aggregate, Release i Manifest pojawiają się obok pliku Compose, dane wyjściowe Aggrega wymieniają, jak zmapowano każdą usługę, oraz zapisane pliki, a powiadomienie informuje, że import utworzył 3 pliki robocze, rozpoznane jako compose.

  • Wiersze warn wymieniają 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 mapped mówią, czym stała się każda usługa. api uruchamia własny obraz, więc jest instancją generycznego serwera biblioteki standardowej, core/compute/server. db i cache uruchamiają te obrazy, które encje Recipes dla Compose z biblioteki standardowej uruchamiają dla core/datastore/postgres i core/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 complete oznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi to aggrega pull, do release.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z --offline import niczego nie pobiera i podaje polecenie aggrega 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/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

Każ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/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"

Ś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/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 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

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

Wersja robocza encji Release otwarta w edytorze po walidacji; dane wyjściowe Aggrega i powiadomienie zgłaszają, że nie znaleziono problemów.

Kompilacja wersji roboczej encji Release: w Eksploratorze pojawia się folder dist, dane wyjściowe Aggrega wymieniają zapisany plik Docker Compose, a powiadomienie informuje, że zapisano 1 plik.

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>/dist

Wiersz 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: 8080

Należ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ść.

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 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:

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

To, co dostarczają połączenia, znajduje się w środowisku usługi API, pod nazwami, które odczytuje 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

Stack zatrzymuje się poleceniem:

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

Na 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:

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

Kompilacja 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:

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

Z 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ć:

Terminal window
aggrega import compose.yaml --sync

Polecenie 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ę.