Stos CloudFormation z dołączeniami
Zarządzana baza danych i odczytująca ją aplikacja, opisane raz jako intencja programisty i złożone w szablony stosów AWS CloudFormation. Dwa dołączenia wnoszą własne zasoby — alarm na bazie danych i parametr wspólnych ustawień na granicy — dlatego ten przykład pokazuje, gdzie zasoby dołączenia trafiają w złożonym stosie i jak są nazywane obok zasobów komponentu.
Ta sama intencja programisty jest budowana na trzy sposoby: jako jeden stos, jako dwa stosy z odwołaniem przechodzącym między nimi oraz — celowo — jako budowanie, które zostaje zatrzymane.
Bloki wyjścia na tej stronie są skopiowane z rzeczywistego uruchomienia, zgodnie z Odczytywanie wyjścia na tych stronach.
Pliki
aggregate.yaml— intencja dewelopera: baza danychpayments-dbtypucore/datastore/mariadborazreporting-apptypuexample/compute/db-reader, który deklaruje, że korzysta z tej bazy danych. Nic dotyczącego AWS się tu nie znajduje. Blokfeatures:bazy danych zawierastorage-headroom, dołączającexample/storage-alarm.release-one-stack.yaml— oba komponenty w jednej granicy, więc oba są składane w jeden stos. Dołączacore/shared-configw całej granicy.release-two-stacks.yaml— ta sama intencja podzielona między dwie granice, więc odwołanie aplikacji do bazy danych przekracza krawędź stosu.release-negative-name-collision.yamlwraz zaggregate-name-collision.yaml— oczekiwane niepowodzenie. Dołącza alarm dwukrotnie do jednego komponentu.manifest.yaml— wiąże każdy typ komponentu i każdy dołączony Feature z encją Recipe, która implementuje go na tym celu..aggrega-config.yaml— wskazuje rejestr hub, z którego rozwiązywane są encje katalogu.
Każde wydanie wiąże slot root_password bazy danych w swoim wpisie dla payments-db, za pomocą core/generated-secret. Na tym celu hasłem administratora zarządza RDS, a encja Recipe bazy danych wybrana przez Manifest zawiera dyrektywę, która to stwierdza; dzięki temu powiązanie jest decyzją operatora, zapisaną w encji Release, a Aggregate nic o nim nie mówi.
Każde wydanie dołącza też core/backup do payments-db, z infra.retention_days: 14, a Manifest wiąże je z cloudformation/backup-native. Jeśli nic nie wskazuje inaczej, RDS przechowuje automatyczne kopie zapasowe instancji przez 7 dni; to dołączenie przechowuje każdą przez 14. Encja FeatureRecipe niczego nie renderuje: kopia zapasowa jest ustawieniem instancji, więc encja Recipe bazy danych odczytuje dołączenie i zapisuje "BackupRetentionPeriod": 14 we własnych Properties instancji.
Wszystkie encje używane w tym przykładzie znajdują się w opublikowanym katalogu. Nic nie jest kopiowane obok plików wydań, więc przykład jest rozwiązywany względem katalogu w jego bieżącym stanie, a nie względem jego prywatnej migawki.
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 cloudformation-rds-stackNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd cloudformation-rds-stackKompilacja
Ten przykład zawiera trzy wydania, więc należy wskazać to, które ma zostać zbudowane. W jednym uruchomieniu buduje się jedno wydanie. Pierwsza kompilacja każdego wydania wymaga jego pliku blokady, który zapisuje pull:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlBudowanie wypisuje (<workspace> oznacza folder tego przykładu):
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distZłożony stos trafia do
dist/one-stack/cloudformation/cloudformation-stack.json. Każdy komponent i
każde dołączenie renderujące się do tego katalogu wnosi swój wkład do tego jednego szablonu —
dostawca emituje pojedynczy stos w czystym JSON zamiast osobnego pliku dla każdego współtwórcy.
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 sam nie twórz żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `cloudformation-rds-stack`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `cloudformation-rds-stack` i bez `dir`: zapisze ono przykład do nowego folderu `cloudformation-rds-stack`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `cloudformation-rds-stack`, `release` ustawionym na `release-one-stack.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisała kompilacja; znajdują się w `cloudformation-rds-stack/dist/`.Co trafia do wyniku i kto to dostarczył
Kompilacja jednego stosu składa cztery zasoby od czterech różnych dostawców:
| Zasób | Dostarczony przez |
|---|---|
PaymentsDb | własną encję Recipe komponentu bazy danych |
PaymentsDbStorageHeadroom | dołączenie storage-headroom na tym komponencie |
AppSharedConfig | dołączenie shared-settings na granicy |
ReportingApp | własną encję Recipe komponentu aplikacji |
Dołączenia backup na payments-db nie ma w tabeli, ponieważ nie wnosi ono własnego zasobu: to, co ustawia, trafia do wnętrza PaymentsDb.
Każdy zasób zawiera blok pochodzenia wskazujący, od kogo pochodzi, dzięki czemu obie części pozostają rozróżnialne w stosie, do którego obie się przyczyniły:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },Dwa wpisy wersji to jedyne wiersze tego bloku, które zmieniają się między
kompilacjami, dlatego je pominięto; trzecie pominięcie to po prostu
Properties alarmu, wydrukowane osobno poniżej. Wszystko, co pokazano, zapisuje
również własna kompilacja.
Alarm jest zasobem dołączenia, a nie bazy danych. Odłączenie
storage-headroom od encji Aggregate usuwa dokładnie ten zasób i jedno
publikowane przez niego wyjście, a PaymentsDb pozostawia bajt w bajt bez zmian.
Nazwa zasobu dołączenia zawiera zakres, który niesie dołączenie
Encja Feature jest tworzona raz i dołączana wiele razy, więc nazwa wyprowadzana
przez FeatureRecipe musi być unikalna dla każdego dołączenia. Ta składa komponent
hosta i nazwę dołączenia: host payments-db, dołączony pod storage-headroom,
daje PaymentsDbStorageHeadroom.
Złożenie samego hosta wystarczyłoby, by alarm nie kolidował z obserwowanym zasobem, ale nie wystarczyłoby, by ta sama encja Feature dołączona dwa razy do jednego komponentu nie kolidowała sama ze sobą — i tego dotyczy niżej opisane wydanie, które kończy się błędem.
Własne właściwości alarmu odwołują się do hosta przez jego wyprowadzoną nazwę:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },Ref na zasobie bazy danych rozwiązuje się do identyfikatora tej instancji podczas
wdrażania stosu. Obie części wyprowadzają PaymentsDb z tej samej nazwy komponentu
i dlatego są zgodne — niczego tu się nie wyszukuje.
Kto decyduje o czym w jednym dołączeniu
Dołączenie dzieli swoje dane wejściowe tak jak komponent. Ile zapasu potrzebuje
aplikacja, to intencja dewelopera, zapisana w dołączeniu w
aggregate.yaml — to właściwość aplikacji. Dokąd alarm wysyła powiadomienia
i jak długo spadek musi trwać, zanim alarm się uruchomi, to wymiarowanie operatora,
dostarczane z encji Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Encja Release dostarcza infra dla dołączenia zadeklarowanego w encji Aggregate, nigdy
values. Wydanie dwóch stosów ustawia oba pola; wydanie jednego stosu żadnego, a
różnicę widać w wyniku. Ustawione:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Nieustawione pole jest nieobecne, a nie puste — alarm jest emitowany bez jakiejkolwiek akcji powiadomienia, a EvaluationPeriods przyjmuje wartość 2 zapisaną w encji Recipe, a nie cokolwiek zadeklarowanego w encji Feature. Encja Release, która nie dostarcza żadnego z nich, nadal otrzymuje działający alarm, a dostarczenie jednego dodaje dokładnie jedno pole.
Wyjścia dołączenia są nazywane od jego hosta, a nie od niego samego
Dwie części stosu są nazywane według różnych reguł i to ta część zaskakuje ludzi.
Logiczny identyfikator zasobu pochodzi z własnej encji Recipe dołączenia — to nazwa podana wyżej.
Wyjście jest nazywane od publikującego komponentu i wpisu łącznie, a w przypadku
dołączenia publikującym komponentem jest host. Alarm publikuje jeden
wpis, alarm-id, który pojawia się jako:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Obie części dają się odczytać, gdy zna się regułę: identyfikator logiczny dopuszcza
tylko litery i cyfry, więc dostawca zapisuje słownie to, czego ten alfabet nie przyjmuje,
zamiast to pomijać — Xzh to wpisany łącznik, a XX to miejsce, gdzie kończy się nazwa
komponentu i zaczyna nazwa wpisu. Do tej nazwy prowadzi payments-db publikujący
alarm-id i nic innego. Nazwy w złożonym
stosie opisują
ten schemat w całości.
To ta sama nazwa wyjścia, jaką uzyskałaby baza danych, gdyby sama
opublikowała alarm-id. Nazwa wpisu, którą publikuje również host, spotkałaby się więc
z wpisem dołączenia w jednej nazwie wyjścia — dlatego nazwy wpisów brzmiące jak
własne nazwy dołączenia nie kolidują z nazwami hosta.
Dołączenie obejmujące całą granicę renderuje się raz dla granicy
core/shared-config jest dołączony w encji Release, na granicy, a nie na
komponencie, i renderuje się raz dla tej granicy — nie raz na każdy komponent
w niej. Kompilacja jednego stosu zawiera dwa komponenty i dokładnie jeden AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },Po skompilowaniu wydania dwóch stosów widać to wyraźniej: każda granica dostaje
własny, z własnymi rozwiązanymi ustawieniami tej granicy. Properties tego zasobu
w każdym z dwóch szablonów zapisywanych przez tę kompilację:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },Jest dołączony w encji Release, ponieważ to, co niesie, jest własnym układem operatora,
a nie czymkolwiek, co deklaruje encja Aggregate. Dołączenie na granicy
ustawia infra:, a nigdy values: — encja Aggregate pozostaje miejscem, w którym
tworzy się wartości dewelopera.
Rozdzielenie tej samej intencji na dwa stosy
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlW aggregate.yaml nic się nie zmienia. Aplikacja nadal deklaruje, że korzysta
z bazy danych; to operator decyduje w encji Release, że obie są provisionowane
oddzielnie, a w efekcie referencja między nimi przekracza krawędź stosu.
W kompilacji z jednym stosem aplikacja otrzymuje endpoint jako referencję wewnątrz jedynego szablonu:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },W kompilacji z dwoma stosami stos producenta publikuje tę wartość jako eksport:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },a stos konsumenta odczytuje ją pod tą samą nazwą:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Tylko host ma Export, ponieważ to jest wpis, który krawędź faktycznie
konsumuje; pozostałe opublikowane wpisy bazy danych pojawiają się jako zwykłe wyjścia.
Alarm w zakresie komponentu podąża za swoim hostem do stosu producenta, a każda granica
zachowuje własne dołączenie obejmujące całą granicę.
Żadna z funkcji wewnętrznych nie jest wyliczana w czasie kompilacji. Endpoint nie istnieje, dopóki stos nie zostanie wdrożony, więc kompilator przekazuje referencję dalej, a CloudFormation ją rozwiązuje — dlatego aplikacja nigdy nie podaje adresu.
Informacje o tym, jak budowana jest nazwa eksportu i kiedy konsument odczytuje wartość przez
Fn::ImportValue zamiast bezpośredniego odczytu między kontami, zawiera sekcja
Połączenia między stosami.
Kompilacja, która się zatrzymuje
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml dołącza alarm dwukrotnie do jednego komponentu,
pod dwiema nazwami dołączeń. Nazwa zasobu każdego dołączenia zawiera jego własną
nazwę dołączenia, więc oba alarmy są dwoma odrębnymi zasobami i w tym miejscu nie kolidują.
Kolidują ich wyjścia: każde publikuje alarm-id, wyjście jest nazywane od
komponentu-hosta i wpisu, a hostem obu jest ten sam komponent.
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")Można z tego odczytać cztery rzeczy i każda z nich jest zamierzona.
- Nazwane są obie strony. Każdy wpis podaje komponent oraz nazwę dołączenia, które przenosił, więc obie można wyszukać w napisanych plikach. Nic w kolizji nie czyni nazwy jednego z autorów tą zamierzoną, dlatego zgłaszane są obie, a nie tylko pierwsza.
- Nazwana jest przestrzeń kluczy.
output-logical-idswskazuje, która z dwóch przestrzeni nazw stosu została osiągnięta, oraz — ponieważ przestrzeni nazw zasobów brak w tym zatrzymaniu — że nazwy zasobów były poprawne. - Nic nie jest emitowane. Kompilacja zatrzymuje się, zamiast zapisać stos, w którym jeden z dwóch alarmów po cichu nie ma wyjścia.
- Rozróżnienie nazw zasobów tego nie naprawia. Nazwa wyjścia jest budowana z komponentu-hosta i wpisu, więc to wpis musi się różnić — albo jedno dołączenie zamiast dwóch, albo encja Feature, której nazwy publikowanych wpisów odczytuje się jako własne nazwy tego dołączenia.
Identyczne wejście, identyczne wyjście
Dwukrotne budowanie z niezmienionych danych wejściowych daje szablony identyczne co do bajtu. Kompilator nie rozwiązuje żadnych danych na żywo — nigdy nie wywołuje AWS, nigdy nie wyszukuje identyfikatora konta i nigdy nie uruchamia CloudFormation — więc ponowne budowanie nie może odkryć niczego, co zmieniłoby bajty. Na tej właściwości opiera się przegląd oparty na porównywaniu różnic.
Katalog dist/ i pliki *.lock są generowane i nie są commitowane; można je
wygenerować ponownie z plików, które są commitowane.