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

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

napisany raz

Na laptopie

release-compose.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

Na klastrze Kubernetes

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Manifesty 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.yaml jest ź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 databases bazy MariaDB; wartość provides.host z Recipe bazy danych jest przekazywana do zmiennej środowiskowej ADMINER_DEFAULT_SERVER Adminera. 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ą Workload agnostyczny wobec możliwości; provider syntetyzuje usługę docker-compose.yaml albo obiekty Kubernetes, których wymaga form danego Workload — Deployment i Service dla bezstanowego interfejsu WWW, a dla bazy danych z form: stateful obiekt StatefulSet, którego szablon żądania wolumenu dla każdej repliki obejmuje katalog danych, wraz z obiektem Headless Service, który nim zarządza, oraz ClusterIP Service, z którym łączą się konsumenci.
  • Podsystem poświadczeń. Hasła do bazy danych są dołączane w filarze features: komponentu — każde jako Feature oznaczony etykietą feature.aggrega.ai/kind: secret, oddzielnie od wartości aplikacji values. featuresSchema encji 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ą bloku inject: w dołączeniu.
  • Zdalne źródła chartów. Zarządzany cel Kubernetes pobiera nadrzędny chart Bitnami MariaDB przez referencję OCI. aggrega pull przypina chart w pliku blokady i pobiera go do pamięci podręcznej adresowanej treścią; aggrega build renderuje z tej pamięci podręcznej, więc w czasie blokowania i w czasie kompilacji rozwiązywany jest ten sam chart. Wersja chartu pochodzi z infra.source_version operatora, 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 poleceniem aggrega pull --release release-<variant>.yaml. Każdy wariant wydania jest rozwiązywany względem własnego, sąsiedniego katalogu, który .aggrega-config.yaml wskazuje dla niego w workspace.releases, więc opcja --catalog nie 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-uri wskazują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-chart komponuje chart zbiorczy: lokalny sub-chart każdego komponentu jest kopiowany dosłownie (jego wyrażenia Helm {{ }} pozostają nienaruszone), a plik values.yaml chartu 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd mariadb-adminer

Kompilacja

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:

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

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

web 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_password to 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_password to slot przezroczysty (inject: [env, file]): poświadczenie udostępnia swoją wartość, a programista mapuje ją na zmienną środowiskową za pomocą bloku inject: 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:

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

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

Terminal window
docker compose -f dist/app/compose/docker-compose.yaml up -d

Należy otworzyć http://localhost:8080 i zalogować się:

PoleWartość
SystemMySQL / MariaDB
Serwerdb (już wypełnione)
Nazwa użytkownikaappuser
Hasłodev-app-pw-change-me
Baza danychappdb

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

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Wynik w dist/app/helm/:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

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

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl port-forward svc/web-default 8080:8080

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

Terminal window
aggrega pull --release release-helm-chart.yaml
aggrega build --release release-helm-chart.yaml

Wynik w dist/app/helm-chart/:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── 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):

Terminal window
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/mariadb i ./charts/adminer są dołączane do chartu parasolowego bez zmian — ich dyrektywy Helm {{ }} nie są modyfikowane przez kompilator i są rozwiązywane podczas helm install. Jedynym zadaniem kompozytora jest tu składanie, a nie szablonowanie. Jedynym polem, które ustawia, jest name każdego umieszczonego Chart.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 przez artifacts: { 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. Artefakt netpol.yaml — o kluczu netpol.yaml i 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.