MariaDB + Adminer — uruchamialny przykład z dwoma celami wdrożenia
Ten przykład kompiluje mały, rzeczywisty stos — bazę danych MariaDB z interfejsem webowym Adminer przed nią — z pojedynczej encji Aggregate napisanej przez programistę na dwie platformy:
- Docker Compose do lokalnego programowania oraz
- Kubernetes dla lokalnego klastra (kind / minikube / k3d), renderowany na trzy sposoby.
Ta sama encja Aggregate steruje oboma. Zmieniają się tylko encja Release, jej Manifest oraz warstwa Recipe ładowana w czasie budowania. Każdy plik tutaj kompiluje się za pomocą dostarczanego CLI aggrega, a wygenerowany wynik działa: wystarczy uruchomić stos, otworzyć Adminer w przeglądarce i zalogować się do działającej bazy danych.
aggregate.yamlnapisany raz
Na laptopie
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlNa klastrze Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifesty Kubernetes
Każda platforma jest kompilowana z własnej encji Release i własnej encji Manifest. Encja Aggregate, która opisuje aplikację, pozostaje taka sama.
Co demonstruje
- Jedna powierzchnia tworzenia, wiele celów. Pojedynczy plik
aggregate.yamljest źródłem prawdy o tym, czym jest stos. Każdy cel to cienka warstwa katalogu, która określa, jak go zrealizować. - String Pipe. Adminer deklaruje użycie
databasesbazy MariaDB; wartośćprovides.hostz Recipe bazy danych jest przekazywana do zmiennej środowiskowejADMINER_DEFAULT_SERVERAdminera. Kompilator przekazuje ten ciąg znaków bez jego interpretowania — dzięki temu kompilacja compose podłącza nazwę usługi compose, a kompilacja Kubernetes podłącza nazwę DNS obiektu Service, z tej samej krawędzi. - Synteza obciążeń. Recipes dla compose i samodzielnego Kubernetes
deklarują
Workloadagnostyczny wobec możliwości; provider syntetyzuje usługędocker-compose.yamlalbo obiekty Kubernetes, których wymagaformdanego Workload —DeploymentiServicedla bezstanowego interfejsu WWW, a dla bazy danych zform: statefulobiektStatefulSet, którego szablon żądania wolumenu dla każdej repliki obejmuje katalog danych, wraz z obiektem HeadlessService, który nim zarządza, orazClusterIPService, z którym łączą się konsumenci. - Podsystem poświadczeń. Hasła do bazy danych są dołączane w filarze
features:komponentu — każde jakoFeatureoznaczony etykietąfeature.aggrega.ai/kind: secret, oddzielnie od wartości aplikacjivalues.featuresSchemaencji Component deklaruje dwa rodzaje slotów, a przykład wykorzystuje oba: slot typu czarna skrzynka, którego FeatureRecipe dostarcza wartość wewnętrznie, oraz slot przezroczysty, którego wartość programista dostarcza jawnie za pomocą blokuinject:w dołączeniu. - Zdalne źródła chartów. Zarządzany cel Kubernetes pobiera nadrzędny
chart Bitnami MariaDB przez referencję OCI.
aggrega pullprzypina chart w pliku blokady i pobiera go do pamięci podręcznej adresowanej treścią;aggrega buildrenderuje z tej pamięci podręcznej, więc w czasie blokowania i w czasie kompilacji rozwiązywany jest ten sam chart. Wersja chartu pochodzi zinfra.source_versionoperatora, jeśli encja Release ją przypina, a w przeciwnym razie z wartości utworzonej przez programistę (wartość trafiająca do rozwiązywania źródła). Pliki blokady poszczególnych wydań przypinają tożsamości i skróty encji: po zmianie nazw encji katalogu lub zmianie ich treści należy odświeżyć nieaktualny lokalny plik blokady poleceniemaggrega pull --release release-<variant>.yaml. Każdy wariant wydania jest rozwiązywany względem własnego, sąsiedniego katalogu, który.aggrega-config.yamlwskazuje dla niego wworkspace.releases, więc opcja--catalognie jest potrzebna ani w terminalu, ani w edytorze, ani przy pracy z asystentem. - Pochodzenie jako adnotacje. Każdy wyrenderowany obiekt Kubernetes zawiera
adnotację
aggrega.ai/recipe-uriwskazującą Recipe, który go utworzył — adnotację, a nie etykietę, ponieważ wartość URI zawiera znaki niedozwolone w wartości etykiety Kubernetes. - Kompozycja chartów (a synteza). Ten sam Aggregate może utworzyć
redystrybuowalny chart Helm zamiast wyrenderowanych manifestów. Provider
helm-chartkomponuje chart zbiorczy: lokalny sub-chart każdego komponentu jest kopiowany dosłownie (jego wyrażenia Helm{{ }}pozostają nienaruszone), a plikvalues.yamlchartu zbiorczego kieruje zmapowane wartości każdego komponentu — w tym przekazany host bazy danych — pod alias tego komponentu. - Wybór encji Provider według typu komponentu. Recipe renderujący każdy komponent to ten, na który Manifest celu mapuje typ tego komponentu, pobierany z tej warstwy katalogu, którą wczytuje kompilacja.
Tworzenie i wykorzystanie — mieszana przestrzeń robocza
Ten przykład obsługuje oba końce katalogu jednocześnie: część encji tworzy lokalnie, a inne wykorzystuje z biblioteki standardowej Aggrega. Encja Component bazy danych MariaDB, jej encje Features z poświadczeniami oraz encje Recipes dla poszczególnych celów są budowane od zera w lokalnych katalogach catalog-*/ — jedna encja Aggregate renderuje tę lokalnie utworzoną bazę danych dla czterech celów. Interfejs webowy Adminer jest natomiast wykorzystywany: komponent web odwołuje się bezpośrednio do dostarczanej encji Component core/devtool/adminer, a każdy cel tworzy jedynie lokalną encję Recipe, która ją implementuje. Ta sama przestrzeń robocza pokazuje zatem tworzenie encji po stronie bazy danych obok wykorzystania katalogu po stronie interfejsu. Encje budowane tutaj są tego samego rodzaju, co encje dostarczane w bibliotece standardowej: encja Component bazy danych, encje Features z poświadczeniami, encje Recipes dostawców.
Przykład catalog-only znajduje się na końcu tego samego programu poświęconym wyłącznie wykorzystaniu: składa dokładnie ten sam stos — bazę danych MariaDB z interfejsem Adminer — odwołując się do encji z biblioteki standardowej, bez tworzenia żadnych własnych. Strona bazy danych w tym przykładzie pokazuje, jak encje katalogu są budowane; przykłady wykorzystania pokazują, jak cały stos jest używany z dostarczanego katalogu.
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example mariadb-adminerNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd mariadb-adminerKompilacja
Każdy cel to jedna encja Release, budowana po jednej na uruchomienie; pull zapisuje lockfile, który odczytuje build. Najpierw Docker Compose — sekcja każdego celu poniżej podaje własne polecenia:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlZ asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `mariadb-adminer`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `mariadb-adminer` i bez `dir`: zapisuje ono przykład w nowym folderze `mariadb-adminer`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `mariadb-adminer`, `release` ustawionym na `release-compose.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj, które pliki zapisała kompilacja; znajdują się w `mariadb-adminer/dist/`.Struktura
mariadb-adminer/├── aggregate.yaml # Developer intent — shared by every target│├── manifest-compose.yaml # Ops mapping, Docker Compose target├── release-compose.yaml # Operator release, Docker Compose target├── catalog-compose/ # Recipe layer: compose│├── manifest-helm-synth.yaml # Ops mapping, self-contained Kubernetes target├── release-helm-synth.yaml # Operator release, self-contained Kubernetes target├── catalog-helm-synth/ # Recipe layer: helm (Workload synthesis)│├── manifest-helm-bitnami.yaml # Ops mapping, managed-chart Kubernetes target├── release-helm-bitnami.yaml # Operator release, managed-chart Kubernetes target├── catalog-helm-bitnami/ # Recipe layer: helm (upstream Bitnami chart)│├── manifest-helm-chart.yaml # Ops mapping, composed-Helm-chart target├── release-helm-chart.yaml # Operator release, composed-Helm-chart target└── catalog-helm-chart/ # Recipe layer: helm-chart (umbrella composition)Każdy katalog catalog-* zawiera lokalnie utworzone definicje encji Component i Feature dla MariaDB oraz encje Recipes dla tego jednego środowiska docelowego. Nie ma wśród nich encji Component dla Adminera — jest ona rozwiązywana z biblioteki standardowej. Kompilacja ładuje jedną warstwę catalog-* nad tą biblioteką standardową, a Manifest celu mapuje każdy typ komponentu na encję Recipe w tej warstwie.
Encja Release, jej aggregate: i jej manifest: znajdują się obok siebie w tym katalogu; katalog, względem którego budowana jest każda encja Release, jest dla niej wskazany w
.aggrega-config.yaml.
Współdzielona encja Aggregate
spec: components: db: type: core/datastore/mariadb values: database: appdb user: appuser charset: utf8mb4 collation: utf8mb4_general_ci chart_version: "25.0.8" # the managed-chart target's chart, absent an operator pin features: root_password: # black-box slot: the FeatureRecipe delivers it type: core/secret-value values: { key: MARIADB_ROOT_PASSWORD, origin: dev-root-pw-change-me } user_password: # transparent slot: the developer delivers it type: core/secret-provided values: { origin: dev-app-pw-change-me } inject: env: [{ in: MARIADB_PASSWORD, from: value }]
web: type: core/devtool/adminer values: design: pepa-linha-dark uses: databases: db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: hostweb deklaruje użycie databases komponentu db. Blok inject wiąże
provides.host z encji Recipe bazy danych ze zmienną środowiskową
ADMINER_DEFAULT_SERVER w kontenerze Adminer. Nic w encji Aggregate nie wskazuje dostawcy;
ten wybór należy w całości do warstwy katalogu, którą wczytuje kompilacja.
Uwaga o poświadczeniach
Obraz MariaDB do uruchomienia potrzebuje hasła roota, a użytkownik aplikacji potrzebuje własnego. Oba są dołączane w filarze features: komponentu bazy danych — oddzielnie od values aplikacji — jako encje Features oznaczone etykietą feature.aggrega.ai/kind: secret. featuresSchema encji Component core/datastore/mariadb deklaruje slot dla każdego z nich, a przykład wykorzystuje oba modele dostarczania:
root_passwordto slot typu czarna skrzynka (inject: []): encja FeatureRecipe dostarcza wartość do potoku komponentu. Programista nie narzuca — i nie może narzucać — sposobu, w jaki to się odbywa.user_passwordto slot przezroczysty (inject: [env, file]): poświadczenie udostępnia swoją wartość, a programista mapuje ją na zmienną środowiskową za pomocą blokuinject:w dołączeniu.
Wartości są tu literałami wpisanymi bezpośrednio, dzięki czemu stos uruchamia się jednym poleceniem — co nadaje się do lokalnego programowania i demonstracji. W środowiskach współdzielonych lub produkcyjnych te same dołączenia pobierają wartości z magazynu sekretów: katalog danego celu wczytuje encję FeatureRecipe, która je pobiera, a encja Aggregate się nie zmienia.
Cel 1 — Docker Compose
Najpierw pull, potem budowanie — pull zapisuje release-compose.lock, który odczytuje budowanie:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlWynik: dist/app/compose/docker-compose.yaml — dwie usługi w jednej sieci.
db uruchamia mariadb:11.4 z bazą danych, użytkownikiem, zestawem znaków i wstrzykniętymi
hasłami; web uruchamia adminer:4, publikuje port 8080, zależy od db i
zawiera ADMINER_DEFAULT_SERVER: db (nazwę usługi compose wyemitowaną przez encję
Recipe bazy danych).
Uruchomienie:
docker compose -f dist/app/compose/docker-compose.yaml up -dNależy otworzyć http://localhost:8080 i zalogować się:
| Pole | Wartość |
|---|---|
| System | MySQL / MariaDB |
| Serwer | db (już wypełnione) |
| Nazwa użytkownika | appuser |
| Hasło | dev-app-pw-change-me |
| Baza danych | appdb |
(lub root / dev-root-pw-change-me). Środowisko usuwa się poleceniem
docker compose -f dist/app/compose/docker-compose.yaml down -v.
Cel 2 — Kubernetes (samodzielny)
Ten cel renderuje zwykłe manifesty Kubernetes bezpośrednio z Workload,
bez zewnętrznego chartu — w ramach jednej kompilacji offline.
Workload bazy danych deklaruje form: stateful, więc syntetyzuje
StatefulSet, którego katalog danych jest szablonem żądania woluminu dla każdej repliki, zamiast
Deployment współdzielącego jedno żądanie. Z tą formą wiążą się dwa elementy towarzyszące:
wolumin jest deklarowany jako persistentTemplate, a bezgłowy Service zapewnia
stabilną tożsamość DNS każdego poda, którą StatefulSet wskazuje jako swoją usługę
nadrzędną. Adminer nie przechowuje stanu, więc jego Workload pozostawia form z wartością domyślną
i pozostaje obiektem Deployment — trwałość jest właściwością encji Workload, a nie
innym komponentem.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlWynik w dist/app/helm/:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080Warto zwrócić uwagę na ADMINER_DEFAULT_SERVER: db-default — dla Kubernetes encja Recipe bazy danych
emituje wewnątrzklastrową nazwę DNS obiektu Service, więc ta sama krawędź w encji Aggregate rozwiązuje się
do routowalnego adresu w tym celu.
Zastosowanie i otwarcie:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Należy otworzyć http://localhost:8080 i zalogować się, podając serwer db-default, nazwę użytkownika
appuser, hasło dev-app-pw-change-me i bazę danych appdb. Usunięcie:
kubectl delete -f dist/app/helm/.
Cel 3 — Kubernetes (zarządzany chart Bitnami)
Trzecia warstwa implementuje ten sam Component core/datastore/mariadb
w oparciu o upstreamowy chart Helm Bitnami MariaDB zamiast syntetyzować
manifesty. Recipe pobiera chart przez referencję OCI i mapuje
wartości encji Component na schemat wartości chartu:
spec: capability: helm implements: core/datastore/mariadb source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` .values.chart_version }}" # operator pin, else the value valuesMapping: | auth: database: "{{ .values.database }}" rootPassword: "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" username: "{{ .values.user }}" password: "{{ .context.inject.env.MARIADB_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}" primary: persistence: size: "{{ .infra.storage.size }}" # … resources, read replicas, metrics mapped from infra …Pole source.version w encji Recipe preferuje wartość infra.source_version operatora i
w razie jej braku używa .values.chart_version utworzonego przez dewelopera. Przypinanie wersji chartu
jest sprawą infrastruktury, więc przypięcie operatora wygrywa wszędzie tam, gdzie
Release je ustawia; ten Release celowo żadnego nie ustawia, więc to klucz .values jest
wersją, która faktycznie zostaje rozwiązana — i to jest cały sens tego celu, ponieważ
wartość dewelopera docierająca do rozwiązywania źródła jest widoczna w renderowanym
wyniku tylko wtedy, gdy brak przypięcia operacyjnego. Po przypięciu source_version w komponencie db
w pliku release-helm-bitnami.yaml renderowana etykieta helm.sh/chart
podąża zamiast tego za tą wersją.
optional odczytuje przypięcie po nazwie, a nie jako ścieżkę z kropkami, i właśnie dzięki temu
brakujące przypięcie przechodzi do wartości dewelopera, zamiast zostać rozwiązane jako pusta
wersja — semantykę sprawdzania obecności opisuje optional.
Budowanie tego celu przebiega w dwóch krokach: aggrega pull rozwiązuje chart,
przypina go w release-helm-bitnami.lock i pobiera do adresowanej treścią
pamięci podręcznej budowania (jedyny krok wymagający sieci); następnie aggrega build renderuje z pamięci podręcznej,
dzięki czemu czas blokowania i czas budowania rozwiązują identyczny chart. Wstrzyknięte dane uwierzytelniające
trafiają do wartości auth chartu, a chart generuje obiekt Kubernetes
Secret, który odczytuje baza danych. Adminer jest renderowany przez ten sam syntetyzowany Recipe
co w celu 2 i łączy się z głównym Service chartu (db-mariadb). Dwa
samodzielne cele opisane wyżej to sposób na uruchomienie całego stosu
bez żadnych zależności.
Cel 4 — Kubernetes (złożony chart Helm)
Czwarta warstwa implementuje te same komponenty względem dostawcy helm-chart,
który składa redystrybuowalny parasolowy chart Helm zamiast
renderować manifesty (Cel 2) lub renderować chart upstream (Cel 3). Każdy
Recipe pobiera niewielki lokalny chart:
spec: capability: helm-chart implements: core/datastore/mariadb source: ./charts/mariadb # copied as the sub-chart, bar its own name valuesMapping: | { "database": "{{ .values.database }}", "rootPassword": "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}", "serviceName": "{{ .context.instance_id }}-mariadb" }Budowanie:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlWynik w dist/app/helm-chart/:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── db/ # the local ./charts/mariadb; its Chart.yaml name is `db`│ ├── Chart.yaml│ ├── values.yaml│ └── templates/│ ├── deployment.yaml│ ├── service.yaml│ ├── pvc.yaml│ └── netpol.yaml # injected artifact (see below)└── web/ # the local ./charts/adminer; its Chart.yaml name is `web` [… omitted: web's own Chart.yaml, values.yaml, and a templates/ holding deployment.yaml and service.yaml — Adminer keeps no state, so it has no pvc.yaml, and the injected netpol.yaml is db's alone]Instalacja (sub-charty są dołączone w charts/, więc wcześniejsze
helm dependency build nie jest potrzebne):
helm install mariadb-adminer dist/app/helm-chart/Plik values.yaml chartu parasolowego zawiera już rozwiązane wartości każdego komponentu, więc
baza danych startuje ze swoimi poświadczeniami, a Adminer jest połączony z serwisem MariaDB
— to samo połączenie, które wyrażają pozostałe cele, teraz dostarczone jako chart,
który można zainstalować lub dołączyć do własnego repozytorium.
Obowiązują dwa odrębne systemy ograniczników, które się nie nakładają:
- Pobrane sub-charty są kopiowane, z wyjątkiem ich własnej nazwy. Pliki w
./charts/mariadbi./charts/adminersą dołączane do chartu parasolowego bez zmian — ich dyrektywy Helm{{ }}nie są modyfikowane przez kompilator i są rozwiązywane podczashelm install. Jedynym zadaniem kompozytora jest tu składanie, a nie szablonowanie. Jedynym polem, które ustawia, jestnamekażdego umieszczonegoChart.yaml, które staje się tożsamością instancji komponentu (db,web), dzięki czemu dwa komponenty dołączające charty o tej samej nazwie pozostają rozróżnialne; zob.providers/helm-chart.md. - Artefakty
$import:używają dwóch rodzajów ograniczników. Recipe może wstrzyknąć dodatkowe pliki szablonów przezartifacts: { name: { $import: ... } }. Te pliki — i tylko one — są wstępnie renderowane przez kompilator z ogranicznikami[[ ]], zanim trafią na miejsce, a ich{{ }}zostaje zachowane dla Helma. Artefaktnetpol.yaml— o kluczunetpol.yamli importowany z./extras/mariadb-netpol.yaml, ponieważ klucz określa nazwę emitowanego pliku, a import wybiera jego treść — pokazuje to połączenie:[[ .context.instance_id ]](wypełniane podczas budowania) i{{ .Release.Namespace }}(pozostawione do instalacji).
String Pipe jest wyrażony w kategoriach chartu: użycie MariaDB w databases przez Adminera
rozwiązuje provides.host z Recipe bazy danych do pliku values.yaml chartu parasolowego
pod aliasem web (adminerDefaultServer: db-mariadb), który sub-chart Adminera
odczytuje jako {{ .Values.adminerDefaultServer }}. Ta sama wartość nazywa
serwis sub-chartu MariaDB, więc połączenie rozwiązuje się spójnie podczas instalacji. Wynikiem
jest chart do helm install lub dołączenia do repozytorium — a nie zestaw zastosowanych manifestów.
Jak wybierany jest cel
Recipe jest wybierany według typu komponentu: Manifest każdego celu mapuje każdy typ na encję Recipe w warstwie katalogu, którą ładuje jego Release, więc manifest-compose.yaml wiąże core/datastore/mariadb z Recipe dla Compose, a manifest-helm-synth.yaml wiąże go z Recipe dla Kubernetesa. Typ, którego Manifest nie mapuje, zatrzymuje kompilację i wskazuje implementujące go encje Recipes, nawet jeśli załadowana warstwa zawiera tylko jedną. Provider renderujący węzeł to spec.capability tego Recipe, który został powiązany. Zmiana celu polega na zmianie encji Release wraz z jej Manifest i katalogiem, który .aggrega-config.yaml dla niej wskazuje — encja Aggregate nigdy się nie zmienia.