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

Jeden kontrakt, trzy realizacje

Baza danych PostgreSQL i aplikacja, która z niej czyta, wdrożone na trzy różne sposoby z jednej niezmienionej encji Aggregate: PostgreSQL działający w klastrze, PostgreSQL jako zarządzana instancja w chmurze oraz serwer PostgreSQL, który istniał już przed wdrożeniem tej encji Release.

Lekcja polega na tym, co się nie zmienia. Aplikacja raz wskazuje klucze, których potrzebuje od bazy danych, oraz nazwy, pod jakimi mają występować. Nigdy nie dowiaduje się, która z trzech odpowiedziała. Kompilator również się tego nie dowiaduje: odczytuje klucze opublikowane przez wybraną encję Recipe i przekazuje dalej ciągi znaków.

Jedyna rzecz, która się zmienia

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

Trzy encje Recipes implementują tę samą encję Component. Każda publikuje te same klucze provides — host, port, user, database, protocol oraz klucze wskazujące, gdzie scraper znajduje metryki bazy danych, puste we wszystkich trzech. To, która z nich działa, określa jedna linia w encji Manifest.

Pliki

  • aggregate.yaml — intencja programisty i ten sam dokument dla wszystkich trzech wdrożeń: komponent db typu core/datastore/postgres, komponent app, który go używa (uses), oraz pięć kluczy, o które prosi aplikacja. Nic tutaj nie wskazuje celu, chmury ani encji Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — mapowania Ops. Każde wybiera swoją realizację jednym wierszem: tym, z którą encją Recipe wiąże się typ komponentu PostgreSQL. Mapowanie zarządzane wiąże też encję Feature kopii zapasowych, którą dołączają jego encje Releases.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — wymiarowanie przez operatora w każdej encji Release: pamięć masowa i wersja silnika dla wdrożenia w klastrze, pamięć masowa, HA i dołączenie core/backup dla wdrożenia zarządzanego oraz adres istniejącego serwera dla wdrożenia z odwołaniem.
  • release-managed-dns.yaml — zarządzana encja Release raz jeszcze, z nazwą DNS, którą operator nadaje instancji, dzięki czemu aplikacja otrzymuje nazwę, którą może rozwiązać.
  • catalog/ — własna encja Component aplikacji i jedyna encja Recipe, która ją renderuje. Wszystko po stronie bazy danych pochodzi z biblioteki standardowej bez modyfikacji.

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 postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

Kompilacja

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull zapisuje plik blokady każdej encji Release przy jej pierwszej kompilacji; późniejsze kompilacje nie potrzebują flagi. Każda kompilacja zapisuje do dist/, a kompilacja dodaje swoje pliki, zamiast czyścić to, co zostawiła poprzednia. Aby przeczytać wynik jednej realizacji osobno, należy usuwać dist/ między uruchomieniami:

Terminal window
rm -rf dist && aggrega build --release release-managed.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 Workspace nie zawiera jeszcze folderu `postgres-three-realizations`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `postgres-three-realizations` i bez `dir`: zapisuje ono przykład w nowym folderze `postgres-three-realizations`. Następnie wywołaj narzędzie `build` raz dla każdej encji Release, w tej kolejności — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` i `release-external.yaml` — za każdym razem z `workspace_root` ustawionym na `postgres-three-realizations`, `release` ustawionym na ten plik, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, jakie pliki zapisała każda kompilacja; znajdują się w `postgres-three-realizations/dist/`.

Co renderuje każda z nich

Self-hosted — serwer uruchamia wdrożenie

helm/postgres syntetyzuje bazę danych w klastrze: StatefulSet, Service typu ClusterIP i headless Service. provides.host to sama nazwa tej usługi Service, więc aplikacja dociera do niej przez DNS wewnątrz klastra.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Managed — serwer uruchamia dostawca chmury

terraform/postgres-rds emituje aws_db_instance jako Terraform HCL, a wymiarowanie ha i dołączenie core/backup ustawione przez operatora przekładają się na natywne ustawienia instancji: retention_days: 14 z dołączenia staje się backup_retention_period = 14 instancji. Aplikacja nadal renderuje się do Kubernetes: obie strony tego wdrożenia spotykają się na opublikowanym kontrakcie bazy danych, a nie na wspólnym celu.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Ta wartość nie jest nazwą hosta i nic w tej kompilacji jej w nią nie zamienia. Adres instancji RDS nie istnieje, dopóki instancja nie zostanie utworzona, więc kompilator działający z wyprzedzeniem nie ma czego wyszukać. To, co publikuje encja Recipe, to referencja Terraform do wyjścia własnego modułu bazy danych; kompilator przekazuje ją przez krawędź bez zmian, encja Recipe aplikacji otrzymuje ją dosłownie, a w manifeście Kubernetes renderuje się ona jako przedstawione wyżej dosłowne znaki. Kontener otrzymuje właśnie ten tekst.

DB_PORT jest inny: renderuje się jako "5432", ponieważ encja Recipe ustawia port instancji na podstawie encji Release i publikuje tę samą wartość, znaną, zanim cokolwiek zaistnieje.

Natywne powiązanie dwóch komponentów to coś, co cel wykonuje we własnym wyjściu, więc tutaj nie ma czego wiązać. Oba końce tej krawędzi renderują się przez różne cele — baza danych do Terraform HCL, aplikacja do manifestu Kubernetes — a referencja Terraform ma znaczenie tylko wewnątrz konfiguracji Terraform. Po przekroczeniu tej granicy opublikowana wartość jest dostarczana jako tekst, jak każdy inny ciąg znaków. Konsument renderowany w Terraform jako encja Recipe typu source:, w tej samej konfiguracji głównej co baza danych, otrzymuje tę samą referencję jako jeden z argumentów swojego modułu i tam Terraform ją rozwiązuje.

To ogólna zasada, a nie przypadek szczególny dla RDS: wszystko, co zależy od stanu działającego systemu, jest wyrażane jako deterministyczny wskaźnik, który rozwiązuje środowisko uruchomieniowe, a nigdy jako wartość pobierana przez kompilator. Rolą kompilatora jest dostarczenie wskaźnika bez zmian. Zadbanie o to, by rozwiązywał się tam, gdzie trafia, należy do autora encji Recipe: należy opublikować adres, którego może użyć strona konsumująca, albo nadać obu komponentom encje Recipes renderujące się do tego samego celu.

Nadanie instancji nazwy, którą aplikacja może rozwiązać

terraform/postgres-rds przyjmuje pierwszą z nich jako opcję ustawianą przez operatora. release-managed-dns.yaml to zarządzana encja Release z jednym dodatkiem — nazwą DNS, którą operator nadaje instancji:

db:
infra:
overrides:
host: db.internal.example.net

Encja Recipe publikuje tę nazwę jako host zamiast referencji Terraform, a aplikacja ją otrzymuje:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
zmiennarelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

To jedyny wiersz wyjścia, który się zmienia. Encja Recipe nie emituje rekordu DNS ani aliasu dla tej nazwy, a kompilacja jej nie wyszukuje: kompilator przekazuje ją dokładnie tak, jak przekazał referencję. Skierowanie db.internal.example.net na instancję, gdy już istnieje — rekord we własnej strefie DNS operatora, wskazujący na adres instancji — należy do operatora, poza encją Release. Klucz jest tym samym, który opisana niżej realizacja z odwołaniem odczytuje dla tego samego adresu; ta encja Recipe przyjmuje go jako samą nazwę lub literał IP, a wartość zawierająca schemat, ścieżkę, użytkownika lub port zatrzymuje kompilację, ponieważ port to infra.port encji Release, a konsument składa swoje połączenie z obu tych wartości.

Konsument renderowany do tej samej konfiguracji Terraform co baza danych również otrzymuje nazwę, a wraz z nią traci kolejność, którą dawała mu referencja: Terraform działa na module po module, do którego ten się odwołuje, a nazwa do niczego się nie odwołuje. Umieszczenie tego konsumenta we własnej granicy, która współdzieli directory: bazy danych i ma późniejszy syncWave:, przywraca kolejność.

External — w tym wdrożeniu nikt nie uruchamia serwera

helm/postgres-external nie tworzy niczego. Całe jego wyjście to jedna usługa Service, która mapuje nazwę wewnątrz klastra na adres dostarczony przez encję Release:

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

Żadnego StatefulSet, żadnego wolumenu, żadnego kontenera — cykl życia serwera leży całkowicie poza tym wdrożeniem. Adres pochodzi z encji Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Odwołanie się do serwera to nie to samo, co przejęcie go. Ta encja Recipe dociera do serwera, który pozostaje własnością zewnętrzną; nic tutaj nie obejmuje go zarządzaniem wdrożenia i nic tutaj go nie zmieni.

Jeśli adres zostanie pominięty, kompilacja się zatrzymuje i to zgłasza. Serwer referencyjny ma adres albo nie ma niczego, więc encja Recipe odmawia, zamiast emitować usługę Service będącą aliasem pustej nazwy:

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

Porównanie, o które tu chodzi

Wyrenderowane środowisko aplikacji, wszystkie trzy warianty obok siebie:

zmiennasamodzielnie hostowanazarządzanazewnętrzna
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Te same zmienne, ta sama kolejność, za każdym razem. Zmienia się tylko ciąg znaków za jedną z nich. Recipe aplikacji nie wymienia żadnej ze zmiennych DB_: emituje to, co rozwiązała krawędź uses, i dlatego jeden Recipe renderuje się bez zmian względem wszystkich trzech baz danych.

Kompilator nie wie też, czym są te ciągi znaków. db-default to nazwa usługi Kubernetes, ${module.db.address} to referencja Terraform, postgres.data.example.net to nazwa DNS — dla kompilatora są to trzy ciągi znaków, które Recipe opublikował pod kluczem host, a krawędź zażądała ich dostarczenia jako DB_HOST. Kompilator nie sprawdza, czy którykolwiek z nich jest routowalny, czy port jest liczbą ani czy komponent o nazwie db jest bazą danych. Dopasował krawędź po etykiecie, którą nosi encja Component, odczytał klucz deklarowany przez kontrakt i przeniósł tekst.

Gdzie przebiega szew

Każde z trzech wdrożeń zostało wybrane przez mapowanie Ops, a ten wybór nie naruszył dokumentu dewelopera. To właśnie ten podział cały przykład ma pokazać w konkretnej postaci:

  • deweloper mówi, czego aplikacja potrzebuje od bazy danych;
  • Ops określa, z czego składa się baza danych — jeden Recipe na każdą realizację;
  • operator określa, którą z nich otrzymuje to wdrożenie, i dobiera jej rozmiar.

Dodanie jutro czwartej realizacji — innej chmury, innego operatora, usługi Compose do pracy lokalnej — oznacza jeszcze jeden Recipe publikujący te same klucze oraz jeden wiersz w encji Manifest. Plik aggregate.yaml w tym katalogu się nie zmienia.